Get the detail of a specific billing run, including per-contract items.

GET /api/customers/recurring-billing/runs/{id} deprecated

Requires: Customers.RecurringBilling.ViewHistory, merchant scope.

Requires API key scope: reports ()

**Required permissions**: `Customers.RecurringBilling.ViewHistory` **Scope**: merchant

Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.

Example request

Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a . See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

cURL

curl -X GET "{{BASE_URL}}/api/customers/recurring-billing/runs/{id}" \
  -H "api-key: {{API_KEY}}"

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$response = Invoke-RestMethod -Method GET -Uri '{{BASE_URL}}/api/customers/recurring-billing/runs/{id}' `
    -Headers $headers

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, RecurringBillingApi } from '@winkpg/winkpg-api';

const api = new RecurringBillingApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.recurringBillingGetRunDetail("3fa85f64-5717-4562-b3fc-2c963f66afa6");

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/customers/recurring-billing/runs/{id}', {
  method: 'GET',
  headers: {
    "api-key": "{{API_KEY}}",
  },
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new RecurringBillingApi(config);
var result = await api.RecurringBillingGetRunDetailAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));

C# (raw HTTP)

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("GET"), "/api/customers/recurring-billing/runs/{id}");
request.Headers.Add("api-key", "{{API_KEY}}");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.RecurringBillingApi(client)
    result = api.recurring_billing_get_run_detail("3fa85f64-5717-4562-b3fc-2c963f66afa6")

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
}

response = requests.request(
    "GET",
    "{{BASE_URL}}/api/customers/recurring-billing/runs/{id}",
    headers=headers,
)
response.raise_for_status()
data = response.json()

Parameters

Name In Type Description

id required

path

string (uuid)

The billing run document ID.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

suppressNulls required

query

boolean

If true, omit properties with null values.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Request body

application/json , required

Field	Type	Description

This request body has no documented fields.

Responses

200 OK

Body: RecurringBillingRunDetailDto RecurringBillingRunDetailDto Each item has these fields.

Field Type Description

summary required

RecurringBillingRunSummaryDto RecurringBillingRunSummaryDto

Summary data for this run.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of RecurringBillingRunSummaryDto:

Field Type Description

id required

string (uuid)

The document ID.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

runId required

string (uuid)

Links all per-merchant run documents from the same workflow execution.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

merchantId required

string (uuid)

The merchant this run was executed for.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

runDate required

string (date-time)

The business date of this billing run.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

triggerType required

RecurringBillingTriggerType RecurringBillingTriggerType

Whether this run was auto or manually triggered.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Auto`	Triggered automatically by the scheduled cron job.
`Manual`	Triggered manually by an administrator via the API or UI.

contractCount required

integer (int32)

Number of contracts processed.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

successCount required

integer (int32)

Number of successful billing attempts.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

failedCount required

integer (int32)

Number of failed billing attempts.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

skippedCount required

integer (int32)

Number of skipped contracts (already billed).

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

totalAmount required

number (double)

Total amount billed across all contracts.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

status required

RecurringBillingRunStatus RecurringBillingRunStatus

Execution status.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Pending`	The run has been created but not yet started.
`Running`	The run is currently executing.
`Completed`	All contracts in the run were processed successfully.
`Failed`	The run failed entirely (infrastructure or unrecoverable error).
`PartiallyCompleted`	Some contracts succeeded and some failed.

correlationId required

string (uuid)

Correlation identifier for distributed tracing. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

durationMs required

integer (int64)

Total duration of the run in milliseconds. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

creationTime required

string (date-time)

When this run was created.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

triggeredByUserId required

string (uuid)

The user who triggered this run (manual triggers only). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

triggeredByUserName required

string

Display name of the triggering user. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

notes required

string

Notes provided with the manual trigger. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

instanceId required

string

Identifier of the background job that processed this run. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

errorMessage required

string

Error message if the run failed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

errorDetails required

array of RecurringBillingRunErrorDetailDto array of RecurringBillingRunErrorDetailDto

Structured failure chain for admin-only diagnostic display. Null unless the caller holds `CustomersPermissions.RecurringBilling.ViewErrorDetails`. Each frame is one link of the exception / Durable `FailureDetails` tree (outer-first). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each RecurringBillingRunErrorDetailDto:

Field Type Description

errorType required

string

Fully qualified CLR type of the exception (or Durable `FailureDetails.ErrorType`). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

errorMessage required

string

Human-readable exception message. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

stackTrace required

string

Demystified stack trace for the frame, if available. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

items required

array of RecurringBillingRunItemDto array of RecurringBillingRunItemDto

Per-contract billing outcomes. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each RecurringBillingRunItemDto:

Field Type Description

contractId required

string (uuid)

The contract that was billed.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

customerId required

string (uuid)

The customer who owns the contract.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

amountBilled required

number (double)

Amount charged.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

success required

boolean

Whether the billing attempt was successful.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

skipped required

boolean

Whether the contract was skipped (already billed).

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

transactionId required

string (uuid)

The transaction created in the payment engine. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

failureReason required

string

Failure reason if the billing attempt failed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

processorResponseCode required

string

Payment processor response code. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

processorMessage required

string

Payment processor message. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

executedAt required

string (date-time)

When the billing execution started. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

completedAt required

string (date-time)

When the billing execution completed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

persistenceFailed required

boolean

True when the contract was charged successfully (`success` = true, `transactionId` populated) but the customer document update that would have written the new `ExecutionHistory` record and advanced `NextScheduledRun` failed at `SaveChangesAsync`. The charge stands; the contract's local view of it is missing until the next billing cycle replays the persistence step (deterministic `IdempotencyKey` prevents re-charge). Null when the row's persistence either succeeded or never ran (skipped/failed). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

persistenceFailureReason required

string

Short label naming the exception type that caused `persistenceFailed` (e.g. `"DbUpdateException"`). Surfaced in the run detail UI so operators can distinguish a transient concurrency conflict from a structural shape bug without leaving the page. Null when `persistenceFailed` is null. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

preCreditAmount required

number (double)

The contract amount this cycle was priced at before any proration credit, pre-surcharge. Null on items written before proration existed and on skips that resolved no amount. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

creditApplied required

number (double)

The proration credit taken off this charge, or null when none applied. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

chargedAmount required

number (double)

The contract amount submitted after the credit, pre-surcharge. Zero for a cycle the credit covered in full; null on items written before proration existed and on skips. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

planPriceId required

string (uuid)

The plan price revision this contract was billed under, or null when the contract carries no plan and on items written before the field existed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

planPriceTotalAmount required

number (double)

What that revision charges per cycle, resolved from the merchant's plan catalog once for the whole run. Null whenever `planPriceId` is, and also when the revision can no longer be read: the plan it belonged to has since been deleted, or the catalog read failed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

planPriceEffectiveFrom required

string (date-time)

When that revision started applying, in UTC. Null under the same conditions as `planPriceTotalAmount`. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

skipCategory required

RecurringBillingSkipCategory RecurringBillingSkipCategory

Why the run did not charge this contract, or null when it did or tried to. Set for every skipped item, and for a failed item whose consent state could not be read. Null on items recorded before this field existed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`AlreadyBilled`	The contract already has a successful charge for this scheduled run. Harmless: nothing is owed, and nothing needs attention.
`MerchantIneligible`	The merchant that owns the contract is missing, deleted, or inactive.
`InvalidContract`	The contract's own per-bill amount is zero or less, so there is nothing to charge.
`PlanUnresolved`	The contract subscribes to a plan whose price could not be read, so the amount is unknown.
`MissingConsent`	The stored payment method has no active stored-credential consent that permits a recurring charge.
`ConsentLookupUnavailable`	The platform could not read the stored payment method's consent state. A platform fault rather than a configuration problem, recorded as a failed run item, and retried on the next run.

This body has no documented fields.

This response has no documented body fields.

403 Forbidden

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

401 Unauthorized

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

400 Bad Request

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

404 Not Found

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

501 Not Implemented

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

500 Internal Server Error

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take. The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

Errors

A failed request returns the platform error envelope. The error reference lists every value error.code can carry and shows the four response shapes.

Codes declared by

The API reference isn't available right now

No such operation

This reference may be out of date

Get the detail of a specific billing run, including per-contract items.

Example request

Parameters

Request body

Responses

200 OK

403 Forbidden

401 Unauthorized

400 Bad Request

404 Not Found

501 Not Implemented

500 Internal Server Error

Errors

Authentication