# 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.signapay-sbx.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.signapay-sbx.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.
  - `PlanNotActive`: The merchant's price plan cannot bill the period: it is marked inactive, its effective-from date falls after the period, or its effective-to date falls before it. Nothing is invoiced or charged, and the run counts the merchant as skipped. The result's error message names which condition failed. The rule is PricePlanBillingState, which the Collection Merchants roster applies too.
- `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.signapay-sbx.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.signapay-sbx.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)
  - `percentageAmountBase` (number(double)): For a fixed plus percentage line, the amount the percentage was taken of: the SKU's or billing group's total recorded amount for the period. Null for every other pricing strategy. (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.signapay-sbx.winkpg.io/docs/api/models/CustomChargeType.md)): (nullable)
    Values:
    - `OneTime`: Charged once only, for the billing period of the month the assignment started.
    - `Monthly`: Charged every monthly billing period.
    - `Quarterly`: Charged every third billing period, counted from the month the assignment started.
    - `Annual`: Charged every twelfth billing period, counted from the month the assignment started.
  - `sortOrder` (integer(int32)): (nullable)

## See also

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