# MerchantBillingHistoryItemDto

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 one merchant's slice of a billing run: a single row in the
per-merchant billing history view. `id` is the owning
billing run's id so the UI can drill into the full run detail page.

## Fields
- `id` (string(uuid))
- `periodKey` (string): Billing period the run covered (yyyyMM). (nullable)
- `runStatus` ([MerchantBillingRunStatus](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingRunStatus.md)): Overall status of the owning billing run. (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.
- `resultStatus` ([MerchantBillingRunResultStatus](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingRunResultStatus.md)): Outcome of this merchant's result within the run. (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.
- `merchantId` (string(uuid)): (nullable)
- `merchantName` (string): Merchant display name snapshot taken at run time. (nullable)
- `pricePlanId` (string(uuid)): (nullable)
- `pricePlanName` (string): Price plan name snapshot taken at run time. (nullable)
- `totalSellAmount` (number(double)): Total amount billed to the merchant for the period. (nullable)
- `currency` (string): (nullable)
- `isDryRun` (boolean): Whether the owning run was a dry (preview) run. (nullable)
- `invoiceId` (string(uuid)): Id of the invoice generated for this result, when the Invoicing path ran. (nullable)
- `startedAt` (string(date-time)): (nullable)
- `completedAt` (string(date-time)): (nullable)
- `creationTime` (string(date-time)): Creation time of the owning billing run (list default sort field).
- `errorMessage` (string): Redacted failure indicator for failed results: the exception type name only, never the raw  exception message. (nullable)
- `lineItems` (array<[BillingRunLineItemDto](https://devportal.demo.winkpg.io/docs/api/models/BillingRunLineItemDto.md)>): Calculated line items for this merchant in this run. (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)

## See also

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