id
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
merchantId
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
merchantName
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
pricePlanId
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
pricePlanName
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
status
required |
MerchantBillingRunResultStatus
MerchantBillingRunResultStatus |
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
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. |
|
fulfillmentPath
required |
BillingFulfillmentPath
BillingFulfillmentPath |
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
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
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
contractId
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
transactionId
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
totalSellAmount
required |
number (double)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
totalBuyAmount
required |
number (double)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
currency
required |
string
|
The ISO 4217 currency the merchant was rated in, from its price plan. Null when no plan was
found, and on a result recorded before the currency was.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
errorMessage
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
declineNoticeSentAt
required |
string (date-time)
|
When the written notice of the declined recurring charge was emailed to the merchant, in UTC.
Null when no notice was sent for the charge this result shows.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
declineNoticeNotSentReason
required |
string
|
Why no decline notice was sent for the declined charge this result shows (for example, the
merchant has no contact email). Null when a notice was sent or none was due.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
lineItems
required |
array of BillingRunLineItemDto
array of BillingRunLineItemDto |
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of each BillingRunLineItemDto:
| Field |
Type |
Description |
|---|
id
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| skuCode
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| displayName
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| pricingStrategy
required |
MerchantBillingPricingStrategy
MerchantBillingPricingStrategy |
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
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
required |
integer (int64)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| billableQuantity
required |
integer (int64)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| percentageAmountBase
required |
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
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| unitBuyRate
required |
number (double)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| unitSellRate
required |
number (double)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| buyAmount
required |
number (double)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| sellAmount
required |
number (double)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| minimumChargeApplied
required |
boolean
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| maximumChargeApplied
required |
boolean
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| isCustomItem
required |
boolean
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| customChargeType
required |
CustomChargeType
CustomChargeType |
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
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
required |
integer (int32)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This body has no documented fields. |
merchantEnvironment
required |
MerchantEnvironment
MerchantEnvironment |
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:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
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
required |
array of BillingRunUnmatchedUsageDto
array of BillingRunUnmatchedUsageDto |
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
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of each BillingRunUnmatchedUsageDto:
| Field |
Type |
Description |
|---|
skuCode
required |
string
|
The SKU code that recorded the usage.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| displayName
required |
string
|
The SKU's display name when the run executed.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| environment
required |
UsageEnvironment
UsageEnvironment |
The environment the SKU meters (Production or Sandbox), when known.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Production |
Production environment. Default for all SKUs. | Sandbox |
Sandbox/developer portal environment with separate quotas. |
| category
required |
string
|
The SKU's category when the run executed, for example Transactions.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| quantity
required |
integer (int64)
|
The quantity that no rate entry priced.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This body has no documented fields. |
percentageVolumeAdvisories
required |
array of BillingRunPercentageVolumeAdvisoryDto
array of BillingRunPercentageVolumeAdvisoryDto |
Fixed plus percentage lines that saw usage but no recorded amount, so they billed their fixed
part only. One entry per line. Empty when every percentage line had an amount to price.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of each BillingRunPercentageVolumeAdvisoryDto:
| Field |
Type |
Description |
|---|
code
required |
string
|
The SKU code, or the billing group code when a group rate entry priced the line.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| displayName
required |
string
|
The line's display name when the run executed.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| quantity
required |
integer (int64)
|
The period quantity the line priced.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| amountBase
required |
number (double)
|
The amount the percentage was taken of.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This body has no documented fields. |