# ContractAggregates

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

Cumulative execution statistics and recent history for a recurring billing contract.

## Fields
- `totalExecutions` (integer(int32))
- `successfulExecutions` (integer(int32))
- `failedExecutions` (integer(int32))
- `amountBilled` (number(double)): (min 0)
- `consecutiveFailures` (integer(int32)): Consecutive failed billing attempts without an intervening success. Reset to 0 on success.  Used with `maxFailCount` to determine suspension. (nullable)
- `lastSuccessfulExecution` (string(date-time)): Timestamp of the last successful billing execution. (nullable)
- `lastExecution` (string(date-time)): Timestamp of the last billing execution (success or failure). (nullable)
- `executionHistory` (array<[ContractExecutionRecord](https://devportal.demo.winkpg.io/docs/api/models/ContractExecutionRecord.md)>): The most recent execution records for this contract (capped at 10, newest first).  May be `null` on older contracts; treat `null` the same as an empty list. (nullable)
  Fields of each item:
  - `executedAt` (string(date-time)): The date and time the billing execution was performed.
  - `success` (boolean): Whether the billing attempt was approved by the payment processor.
  - `amountBilled` (number(double)): The amount charged in this billing execution.
  - `transactionId` (string(uuid)): The transaction ID created in the payment engine, if one was created. (nullable)
  - `failureReason` (string): An explanation of why the billing execution failed. Null for successful attempts. (nullable)
  - `responseCode` (string): The processor response code for this execution. Used for failure classification  against `failureRetryResultCodes`. (nullable)
  - `scheduledRunTime` (string(date-time)): The scheduled occurrence time this execution was triggered for.  Used by the Layer 2 idempotency guard to detect duplicate billing for the same  scheduled occurrence. Null for execution records created before this field was added. (nullable)
  - `preCreditAmount` (number(double)): The contract amount this cycle was priced at before any proration credit was applied: the  inline per-bill total, or the plan revision in force. Pre-surcharge, so it is the number a  later cycle compares against to detect a mid-cycle price change (`amountBilled`  is the processor's response amount and may include a surcharge). Null on records written  before proration existed; such a record never seeds a proration credit. (nullable)
  - `creditApplied` (number(double)): The proration credit taken off this charge, or null when none applied. Zero is never  written; a cycle with no credit leaves the field absent. (nullable)
  - `chargedAmount` (number(double)): The contract amount actually submitted for this cycle after the credit:  `preCreditAmount` less `creditApplied`, floored at zero. Pre-surcharge,  like the two fields it derives from. Null on records written before proration existed. (nullable)
  - `planPriceId` (string(uuid)): The plan price revision this charge was billed under, or null when the contract carries no  plan and bills its own inline amounts. Null too on records written before the field existed. (nullable)
  - `planId` (string(uuid)): The plan the revision in `planPriceId` belongs to. Written together with it, and  null under exactly the same conditions. (nullable)
- `pendingCredit` (number(double)): A proration credit still owed to the customer, to be taken off the next charge, or  `null` (equivalently zero) when none is owed. (nullable)
- `lastBillingSkip` ([ContractBillingSkip](https://devportal.demo.winkpg.io/docs/api/models/ContractBillingSkip.md)): The most recent billing run that found this contract due and did not charge it, and why, or  `null` when the last run that looked at the contract charged it (or none has  skipped it). Read-only: the billing engine is the only writer. (nullable, read only)
  Fields:
  - `skippedAt` (string(date-time)): When the run decided not to charge the contract, in UTC.
  - `scheduledRunTime` (string(date-time)): The scheduled charge the run did not make, in UTC.
  - `category` ([RecurringBillingSkipCategory](https://devportal.demo.winkpg.io/docs/api/models/RecurringBillingSkipCategory.md)): Why the run did not charge the contract.
    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.
  - `reason` (string): The billing engine's explanation of the skip, at most `MaxReasonLength`  characters. Never carries payment credential data. (nullable)

## See also

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