# RecurringBillingRunDetailDto

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

Detail DTO for a recurring billing run, including per-contract items.

## Fields
- `summary` ([RecurringBillingRunSummaryDto](https://devportal.demo.winkpg.io/docs/api/models/RecurringBillingRunSummaryDto.md)): Summary data for this run.
  Fields:
  - `id` (string(uuid)): The document ID.
  - `runId` (string(uuid)): Links all per-merchant run documents from the same workflow execution.
  - `merchantId` (string(uuid)): The merchant this run was executed for.
  - `runDate` (string(date-time)): The business date of this billing run.
  - `triggerType` ([RecurringBillingTriggerType](https://devportal.demo.winkpg.io/docs/api/models/RecurringBillingTriggerType.md)): Whether this run was auto or manually triggered.
    Values:
    - `Auto`: Triggered automatically by the scheduled cron job.
    - `Manual`: Triggered manually by an administrator via the API or UI.
  - `contractCount` (integer(int32)): Number of contracts processed.
  - `successCount` (integer(int32)): Number of successful billing attempts.
  - `failedCount` (integer(int32)): Number of failed billing attempts.
  - `skippedCount` (integer(int32)): Number of skipped contracts (already billed).
  - `totalAmount` (number(double)): Total amount billed across all contracts.
  - `status` ([RecurringBillingRunStatus](https://devportal.demo.winkpg.io/docs/api/models/RecurringBillingRunStatus.md)): Execution status.
    Values:
    - `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` (string(uuid)): Correlation identifier for distributed tracing. (nullable)
  - `durationMs` (integer(int64)): Total duration of the run in milliseconds. (nullable)
  - `creationTime` (string(date-time)): When this run was created.
- `triggeredByUserId` (string(uuid)): The user who triggered this run (manual triggers only). (nullable)
- `triggeredByUserName` (string): Display name of the triggering user. (nullable)
- `notes` (string): Notes provided with the manual trigger. (nullable)
- `instanceId` (string): Identifier of the background job that processed this run. (nullable)
- `errorMessage` (string): Error message if the run failed. (nullable)
- `errorDetails` (array<[RecurringBillingRunErrorDetailDto](https://devportal.demo.winkpg.io/docs/api/models/RecurringBillingRunErrorDetailDto.md)>): 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)
  Fields of each item:
  - `errorType` (string): Fully qualified CLR type of the exception (or Durable `FailureDetails.ErrorType`). (nullable)
  - `errorMessage` (string): Human-readable exception message. (nullable)
  - `stackTrace` (string): Demystified stack trace for the frame, if available. (nullable)
- `items` (array<[RecurringBillingRunItemDto](https://devportal.demo.winkpg.io/docs/api/models/RecurringBillingRunItemDto.md)>): Per-contract billing outcomes. (nullable)
  Fields of each item:
  - `contractId` (string(uuid)): The contract that was billed.
  - `customerId` (string(uuid)): The customer who owns the contract.
  - `amountBilled` (number(double)): Amount charged.
  - `success` (boolean): Whether the billing attempt was successful.
  - `skipped` (boolean): Whether the contract was skipped (already billed).
  - `transactionId` (string(uuid)): The transaction created in the payment engine. (nullable)
  - `failureReason` (string): Failure reason if the billing attempt failed. (nullable)
  - `processorResponseCode` (string): Payment processor response code. (nullable)
  - `processorMessage` (string): Payment processor message. (nullable)
  - `executedAt` (string(date-time)): When the billing execution started. (nullable)
  - `completedAt` (string(date-time)): When the billing execution completed. (nullable)
  - `persistenceFailed` (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)
  - `persistenceFailureReason` (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)
  - `preCreditAmount` (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)
  - `creditApplied` (number(double)): The proration credit taken off this charge, or null when none applied. (nullable)
  - `chargedAmount` (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)
  - `planPriceId` (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)
  - `planPriceTotalAmount` (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)
  - `planPriceEffectiveFrom` (string(date-time)): When that revision started applying, in UTC. Null under the same conditions as  `planPriceTotalAmount`. (nullable)
  - `skipCategory` ([RecurringBillingSkipCategory](https://devportal.demo.winkpg.io/docs/api/models/RecurringBillingSkipCategory.md)): 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:
    - `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.

## See also

- [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.