Fixed-price subscription troubleshooting

Use the following checks before repeating a subscription or invoice request.

The plan can't be used#

Confirm that:

• The plan exists in the same account, store, mode, and environment as the request.
• The plan is active.
• Every referenced product exists and is active.
• Products used to derive a plan amount use the same currency.

The payment token isn't accepted#

Confirm that:

• Card details were collected through the XPay Element.
• The token was received from the verified webhook at token.id.
• The request uses payment.token.
• The token exists in the same environment and is enabled.
• The merchant isn't sending the token already attached to the subscription in an update request.

The start date is rejected#

start_date must be a valid ISO 8601 date-time and can't be earlier than the current time. Supply a supported timezone.

When a plan has billing_cycle_anchor_config, XPay aligns the first scheduled invoice to that anchor. A day that doesn't exist in the target month rolls into the following month.

Advance payment failed#

• failure_action: "CANCEL": XPay doesn't create the subscription.
• failure_action: "CONTINUE": XPay creates the subscription with draft state.

Store and reconcile the returned subscription ID before deciding the merchant's next action.

A scheduled invoice can't be retrieved#

The ID can be reserved in scheduled_invoices before the invoice object is created. Retrieve it again when its billing date arrives, or use the subscription response to show the upcoming schedule.

Skip is rejected#

Confirm that:

• The request uses type: "invoice_id".
• The invoice ID exists in scheduled_invoices.
• The subscription isn't paused or cancelled.
• Past-due skip is enabled when the subscription is inactive.

Pause, resume, or cancel is rejected#

• Pause supports the immediate flow documented in this guide.
• Only a paused subscription can be resumed.
• A paused or cancelled subscription can't be cancelled again.
• Past-due pause or cancellation must be allowed when the subscription is inactive.

Retry timing is rejected#

The number of payment_retries_timing entries must equal the allowed retry count. Each entry must provide non-negative date, hour, and minute offsets.

Payment remains unsuccessful#

Retrieve the invoice and confirm:

• Current invoice state
• Latest payment-attempt result
• Whether attempts remain
• Whether the payment token is still enabled

Use the invoice payment endpoint, mark-paid endpoint, or a payment link to recover the subscription. A successful payment returns the subscription to paid. See Failed payments and retries for the recovery flow.