# RecurringBillingRunItemDto

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

DTO for a single contract billing outcome within a run.

## Fields
- `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.