# BillingRunResultDto

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 per-merchant billing run result.

## Fields
- `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)
  Fields of each item:
  - `id` (string(uuid)): (nullable)
  - `skuCode` (string): (nullable)
  - `displayName` (string): (nullable)
  - `pricingStrategy` ([MerchantBillingPricingStrategy](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingPricingStrategy.md)): (nullable)
    Values:
    - `Fixed`: A fixed amount per billing period regardless of usage quantity.
    - `PerUnit`: A per-unit rate multiplied by the usage quantity.
    - `Tiered`: Per-unit rates that vary by quantity brackets (tiers).
    - `FixedPlusPercentage`: A fixed base amount plus a percentage of the transaction amount or volume.
  - `rawQuantity` (integer(int64)): (nullable)
  - `billableQuantity` (integer(int64)): (nullable)
  - `unitBuyRate` (number(double)): (nullable)
  - `unitSellRate` (number(double)): (nullable)
  - `buyAmount` (number(double)): (nullable)
  - `sellAmount` (number(double)): (nullable)
  - `minimumChargeApplied` (boolean): (nullable)
  - `maximumChargeApplied` (boolean): (nullable)
  - `isCustomItem` (boolean): (nullable)
  - `customChargeType` ([CustomChargeType](https://devportal.demo.winkpg.io/docs/api/models/CustomChargeType.md)): (nullable)
    Values:
    - `OneTime`: Charged once only (first billing run after assignment).
    - `Monthly`: Charged every monthly billing period.
    - `Quarterly`: Charged every quarterly billing period.
    - `Annual`: Charged every annual billing period.
  - `sortOrder` (integer(int32)): (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)
  Fields of each item:
  - `skuCode` (string): The SKU code that recorded the usage. (nullable)
  - `displayName` (string): The SKU's display name when the run executed. (nullable)
  - `environment` ([UsageEnvironment](https://devportal.demo.winkpg.io/docs/api/models/UsageEnvironment.md)): The environment the SKU meters (Production or Sandbox), when known. (nullable)
    Values:
    - `Production`: Production environment. Default for all SKUs.
    - `Sandbox`: Sandbox/developer portal environment with separate quotas.
  - `category` (string): The SKU's category when the run executed, for example Transactions. (nullable)
  - `quantity` (integer(int64)): The quantity that no rate entry priced. (nullable)

## See also

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