Usage-based billing troubleshooting

Use this checklist when XPay rejects a meter, pricing model, plan, subscription, or meter event.

A meter event is rejected#

Confirm that:

• The meter ID exists and is active.
• The subscription is eligible and isn't inactive, paused, or cancelled.
• The subscription's plan is active and contains a pricing model referencing the meter.
• aggregation_field exactly matches the meter.
• value is positive.
• The timestamp is a valid ISO 8601 value and is not earlier than the current time.
• A fixed-retainer meter isn't receiving events.

Usage appears more than once#

XPay doesn't enforce event_id uniqueness. Check whether the merchant submitted the same logical event more than once, including submissions with different event IDs. Use Prevent duplicate meter events to assign stable identifiers and track request outcomes.

Recent usage isn't visible on an invoice#

Confirm that:

• The event was accepted for the same subscription and meter.
• The event belongs to the ongoing invoice cycle.
• The invoice object has been generated.
• The expected pricing model appears in pricing_model_breakdown.

XPay doesn't provide a separate aggregated-usage preview operation. Use the generated invoice as the reconciliation record.

REMOVE is rejected#

REMOVE requires:

• A sum or count meter.
• A standard or percentage pricing model component.
• Enough incurred usage to keep the result at or above zero.

For count, one REMOVE event subtracts one count regardless of its positive value.

The subscription is inactive or paused#

Retrieve the subscription before reporting usage. Meter events are rejected for inactive, paused, or cancelled subscriptions. Recover the failed invoice or resume the subscription through the supported flow before submitting new usage.

The pricing model can't be created#

Confirm that:

• Every component references an existing active meter.
• A non-composite model has exactly one component.
• The component pricing_type matches the model's charge_type.
• A composite model has exactly two components with different meter IDs and pricing types.
• Tier ranges begin at 1, have no gaps, and end with "Infinity".
• A recurring model doesn't use tiered or volume pricing.
• currency is supplied.

The pricing model can't be attached#

Confirm that:

• The plan has is_usage_based: true.
• pricing_models is a non-empty array of unique IDs.
• Every pricing model belongs to the same account, store, mode, and environment as the plan.
• All pricing models on the plan have the same type.
• An appended pricing model isn't already attached.

Invoice payment failed#

Retrieve both the invoice and subscription:

• The subscription becomes inactive after a failed recurring payment.
• XPay uses the configured payment retry schedule.
• Paying or marking the invoice as paid returns an eligible subscription to paid.

The usage-based subscription can't be created#

Confirm that:

• The plan is active and usage-based.
• The plan contains at least one pricing model.
• The payment request uses payment.token or an eligible XPay customer.
• The payment token exists and is enabled.
• start_date isn't earlier than the current time.
• collect_advance is false or omitted.