# PricePlanHistoryDto

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

Plan-scoped historic billing report: every billing-run outcome where a merchant was
billed against the requested price plan, ordered by merchant then period.

## Fields
- `pricePlanId` (string(uuid)): The price plan the report is scoped to.
- `currentPlanName` (string): The plan's <b>current</b> name (row-level names are run-time snapshots). (nullable)
- `fromPeriodKey` (string): Inclusive start of the effective period range (yyyyMM). (nullable)
- `toPeriodKey` (string): Inclusive end of the effective period range (yyyyMM). (nullable)
- `rows` (array<[PricePlanHistoryRowDto](https://devportal.demo.winkpg.io/docs/api/models/PricePlanHistoryRowDto.md)>): Report rows, sorted by merchant name then period. (nullable)
  Fields of each item:
  - `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.