# BillingRunDto

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

Output DTO for a merchant billing run.

## Fields
- `id` (string(uuid))
- `creationTime` (string(date-time)): The date and time when this entity was created.
- `creatorId` (string(uuid)): The ID of the user who created this entity. (nullable)
- `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. (nullable)
- `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. (nullable)
- `isDeleted` (boolean): Indicates whether this entity has been deleted.
- `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. (nullable)
- `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. (nullable)
- `resellerId` (string(uuid)): (nullable)
- `resellerName` (string): Display name of the reseller the run billed. Populated on list reads, where runs of the  caller's own reseller and of resellers beneath it can appear; null when it cannot be resolved. (nullable)
- `periodKey` (string): (nullable)
- `status` ([MerchantBillingRunStatus](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingRunStatus.md)): (nullable)
  Values:
  - `Pending`: Billing run created but not yet started.
  - `Running`: Billing run is currently processing merchants.
  - `Completed`: All merchants processed successfully.
  - `PartiallyCompleted`: Some merchants processed successfully, others failed.
  - `Failed`: All merchants failed or the run itself failed.
  - `Cancelled`: Billing run was manually cancelled.
- `triggerType` ([BillingRunTriggerType](https://devportal.demo.winkpg.io/docs/api/models/BillingRunTriggerType.md)): (nullable)
  Values:
  - `Manual`: Triggered manually by a user through the UI or API.
  - `Scheduled`: Triggered automatically by the scheduled billing job.
  - `ManualBatch`: One reseller's share of a billing run an administrator started for all resellers at once. It runs as a background job under a system identity, like Scheduled.
- `isDryRun` (boolean): (nullable)
- `totalMerchants` (integer(int32)): (nullable)
- `successCount` (integer(int32)): (nullable)
- `failureCount` (integer(int32)): (nullable)
- `skippedCount` (integer(int32)): (nullable)
- `totalBilledAmount` (number(double)): (nullable)
- `currency` (string): (nullable)
- `orchestrationInstanceId` (string): (nullable)
- `startedAt` (string(date-time)): (nullable)
- `completedAt` (string(date-time)): (nullable)
- `cancelledByUserId` (string(uuid)): (nullable)
- `cancelledByUserName` (string): (nullable)
- `cancelReason` (string): (nullable)
- `failureReason` (string): Diagnostic reason a run reached `Failed` (e.g. processing  was interrupted by a host restart). Null when the run did not fail or predates this field. (nullable)
- `merchantResults` (array<[BillingRunResultDto](https://devportal.demo.winkpg.io/docs/api/models/BillingRunResultDto.md)>): (nullable)
  Fields of each item:
  - `id` (string(uuid)): (nullable)
  - `merchantId` (string(uuid)): (nullable)
  - `merchantName` (string): (nullable)
  - `pricePlanId` (string(uuid)): (nullable)
  - `pricePlanName` (string): (nullable)
  - `status` ([MerchantBillingRunResultStatus](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingRunResultStatus.md)): (nullable)
    Values:
    - `Success`: Merchant rated successfully. Terminal for a dry run; on a non-dry run it is a transient pre-dispatch state that the fulfillment dispatcher advances to a path-specific status (Invoiced or ChargePending).
    - `Failed`: Billing failed for this merchant.
    - `Skipped`: Merchant was skipped (e.g., inactive or excluded).
    - `NoPlan`: No active price plan assigned to this merchant.
    - `NoUsage`: No usage recorded for this merchant in the billing period.
    - `NoFulfillmentPath`: Neither ResellerBillingPreferences.DefaultFulfillmentPath nor the per-merchant MerchantBillingAssignment.FulfillmentPath override is set, so the resolver cannot decide how to collect payment for this merchant.
    - `NoPaymentMethod`: The effective fulfillment path is RecurringContract but no active MerchantBillingPaymentMethod row exists for the (ResellerId, MerchantId) pair, so the recurring charge has no token to draft against.
    - `MissingCollectionMerchant`: The effective fulfillment path is RecurringContract but the reseller has not configured a CollectionMerchantId, so there is no party to own the recurring contract.
    - `MissingHpp`: The effective fulfillment path is Invoicing but the reseller has not configured an HppPageId, so the generated invoice has no payment link destination.
    - `Invoiced`: The merchant was rated successfully and the Invoicing fulfillment path produced an issued invoice. Terminal for the Invoicing path: see MerchantBillingRunResult.InvoiceId for the artifact.
    - `Charged`: The RecurringContract path charge completed successfully. Set when the downstream charge reconciliation (tracked separately) confirms an approved transaction; see MerchantBillingRunResult.TransactionId.
    - `ChargePending`: The merchant was rated successfully and the RecurringContract path dispatched a charge request into the Transaction Manager. The charge has not yet been reconciled; the run records this as a non-terminal "awaiting result" state. See MerchantBillingRunResult.ContractId.
    - `ChargeFailed`: The RecurringContract path charge was attempted but declined or errored. Set by the downstream charge reconciliation (tracked separately).
    - `NoBillableUsage`: Usage was recorded for the merchant in the billing period, but the plan produced no positive-charge line item, so there is nothing to bill. Distinct from NoUsage (which means no usage aggregates existed at all): here the merchant genuinely transacted, the usage simply fell entirely within a rate entry's included/free allowance or matched no billable rate entry. Where a rate entry matched the usage, the rated run keeps the zero-billable line item visible so the operator can see the usage and why it was not charged; usage that matched no rate entry produces no line item.
  - `fulfillmentPath` ([BillingFulfillmentPath](https://devportal.demo.winkpg.io/docs/api/models/BillingFulfillmentPath.md)): (nullable)
    Values:
    - `Invoicing`: Generate an invoice in PhoeniXGate.Invoicing addressed to the Merchant and route payment through the reseller's configured Hosted Payment Page.
    - `RecurringContract`: Charge a stored payment method (card or ACH) against the Merchant on a schedule, via a recurring contract owned by the reseller's collection merchant.
  - `invoiceId` (string(uuid)): (nullable)
  - `contractId` (string(uuid)): (nullable)
  - `transactionId` (string(uuid)): (nullable)
  - `totalSellAmount` (number(double)): (nullable)
  - `totalBuyAmount` (number(double)): (nullable)
  - `errorMessage` (string): (nullable)
  - `lineItems` (array<[BillingRunLineItemDto](https://devportal.demo.winkpg.io/docs/api/models/BillingRunLineItemDto.md)>): (nullable)
  - `merchantEnvironment` ([MerchantEnvironment](https://devportal.demo.winkpg.io/docs/api/models/MerchantEnvironment.md)): The merchant's environment when the run billed it (Sandbox, PendingPromotion, Production or  Suspended). Null for a result recorded before the environment was captured. (nullable)
    Values:
    - `Sandbox`: The merchant transacts against the processor's test host. No live money moves. This is the fail-closed default for anything whose environment cannot be determined.
    - `PendingPromotion`: The merchant has requested promotion to production and is awaiting approval. It may not transact against any endpoint while in this state.
    - `Production`: The merchant transacts against the processor's live host. The only state that resolves a production endpoint.
    - `Suspended`: The merchant has been administratively suspended. It may not transact against any endpoint, live or test, until it is returned to another state.
  - `unmatchedUsage` (array<[BillingRunUnmatchedUsageDto](https://devportal.demo.winkpg.io/docs/api/models/BillingRunUnmatchedUsageDto.md)>): Usage recorded in the billed period that no rate entry on the plan priced, one entry per  SKU. Empty when every recorded SKU was priced. (nullable)
- `preSelectionExclusions` (array<[BillingRunExclusionDto](https://devportal.demo.winkpg.io/docs/api/models/BillingRunExclusionDto.md)>): Merchants excluded before selection with the reason each was skipped. Lets the detail UI  explain a lower-than-expected billed count instead of silently omitting them. (nullable)
  Fields of each item:
  - `merchantId` (string(uuid)): (nullable)
  - `merchantName` (string): (nullable)
  - `reason` ([BillingRunPreSelectionReason](https://devportal.demo.winkpg.io/docs/api/models/BillingRunPreSelectionReason.md)): (nullable)
    Values:
    - `Inactive`: The merchant is deactivated, so a billing run must not bill it. These merchants are filtered out by the billing-assignment lookup's active-state query filter; the run records them here purely so the operator can see why the count is lower. (Soft-deleted merchants remain hidden and are not surfaced as exclusions.)
    - `NoPricePlanAssigned`: The merchant's billing assignment has no price plan (PricePlanId is null/empty), so there is nothing to rate against.
    - `EffectiveWindowOutsidePeriod`: The billing assignment's effective window (EffectiveFrom/EffectiveTo) does not overlap the billed period: e.g. a plan whose effective date is after the billed month. This is the exact confusion behind the effective-date billing investigation: a merchant is assigned to a plan but skipped because the assignment is not effective for the period.
  - `effectiveFrom` (string(date-time)): (nullable)
  - `effectiveTo` (string(date-time)): (nullable)
- `concurrencyStamp` (string): (nullable)

## See also

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