# PricePlanHistoryRowDto

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

One merchant × billing-run outcome for the plan-scoped historic report. All display
fields are snapshots captured at run time (merchant name, plan name) so the report
reflects the plan as it existed when the run executed, not the current plan.

## Fields
- `merchantId` (string(uuid)): The billed merchant. (nullable)
- `merchantName` (string): Merchant name snapshot at billing time. (nullable)
- `periodKey` (string): Billing period key (yyyyMM). (nullable)
- `planNameSnapshot` (string): Price plan name snapshot at billing time. (nullable)
- `totalFees` (number(double)): Total sell-side fees charged to the merchant for the period. (nullable)
- `paymentStatus` ([PricePlanHistoryPaymentStatus](https://devportal.demo.winkpg.io/docs/api/models/PricePlanHistoryPaymentStatus.md)): Coarse payment status derived from the run-result status.
  Values:
  - `NotApplicable`: Not applicable: the merchant was not billed (skipped/unresolved).
  - `Paid`: Charge confirmed (recurring path reconciled).
  - `Pending`: Awaiting payment: invoice issued or charge dispatched but not reconciled.
  - `Failed`: Billing or charge failed for this merchant.
- `resultStatus` ([MerchantBillingRunResultStatus](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingRunResultStatus.md)): The raw per-merchant run-result status. (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)): How the charge was (or would be) collected. (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.
- `billingRunId` (string(uuid)): The billing run this row came from (links to the run detail page).
- `invoiceId` (string(uuid)): Generated invoice, when the Invoicing path produced one. (nullable)
- `runCompletedAt` (string(date-time)): When the billing run completed. (nullable)

## See also

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