Manage a fixed-price subscription

Use the subscription-management operations to update billing details, skip an upcoming invoice, pause or resume billing, or cancel a subscription.

Retrieve the subscription before changing it and use the XPay API reference for the complete schema of each operation.

Retrieve a subscription#

GET {{base_url}}/public/v1/subscription/{subscription_id}

Use the returned subscription state and invoice lists to decide whether the requested action is available.

Update a subscription#

PATCH {{base_url}}/public/v1/subscription/{subscription_id}

The update operation can change supported subscription details such as:

• Name and metadata
• Plan
• Products and quantities
• Payment token or XPay customer
• Amount and currency
• Start date, timezone, and billing cycle
• Payment retry timing

Update metadata and payment token#

{
  "metadata": {
    "merchant_customer_id": "customer-1001"
  },
  "payment": {
    "token": "{{replacement_payment_token}}"
  }
}

The replacement token must exist and be enabled. Don't send the same token that is already attached to the subscription.

Move to another plan#

{
  "plan_id": "{{new_plan_id}}"
}

When plan_id is supplied, XPay takes the billing cycle, products, amount, and currency from the selected plan. Don't combine plan_id with separate interval, amount, or currency values in the same request.

See Prorations when the plan change should create a proration invoice for the current billing cycle.

Skip an upcoming invoice#

POST {{base_url}}/public/v1/subscription/{subscription_id}/skip

XPay supports skipping one scheduled invoice by its reserved invoice ID:

{
  "type": "invoice_id",
  "invoice_id": "{{scheduled_invoice_id}}"
}

Skipping moves the selected entry from scheduled_invoices to skipped_invoices. It doesn't create an invoice with a skipped state.

XPay sends subscription_skip after a successful skip. See Fixed-price subscription webhooks.

Paused and cancelled subscriptions can't be skipped. An inactive subscription can be skipped only when the merchant's subscription settings allow past-due skip operations.

Unskip an invoice#

POST {{base_url}}/public/v1/subscription/{subscription_id}/unskip

{
  "type": "invoice_id",
  "invoice_id": "{{skipped_invoice_id}}"
}

The unskip operation moves the entry back into scheduled_invoices. If its scheduled date has passed, collect payment through the invoice payment API or a payment link instead of restoring the old schedule entry.

Pause immediately#

POST {{base_url}}/public/v1/subscription/{subscription_id}/pause

{
  "type": "immediate",
  "proration": false
}

A paused or cancelled subscription can't be paused again. An inactive subscription can be paused only when the merchant's subscription settings allow past-due pause operations.

Resume a subscription#

POST {{base_url}}/public/v1/subscription/{subscription_id}/resume

Choose how billing resumes:

{
  "billing_cycle": "now"
}

• now: XPay attempts payment immediately. If payment succeeds, the subscription becomes paid and future dates are calculated from the resumed cycle.
• retain: XPay retains the existing billing-cycle alignment, restores future invoices, and returns the subscription to draft until its next successful payment.

Only a paused subscription can be resumed.

Cancel a subscription#

POST {{base_url}}/public/v1/subscription/{subscription_id}/cancel

Cancel immediately#

{
  "cancellation_reason": "Customer requested cancellation"
}

Cancel immediately and defer the webhook#

{
  "end_of_invoice": true,
  "cancellation_reason": "Customer requested cancellation"
}

With end_of_invoice: true, XPay sends the cancellation webhook when the next invoice would otherwise have become due.

A merchant can alternatively supply a future ISO 8601 timestamp in time. The subscription is still cancelled immediately; only the webhook is deferred until that time.

Paused and already-cancelled subscriptions can't be cancelled. An inactive subscription can be cancelled only when the merchant's subscription settings allow past-due cancellation.

Process the result#

After every management request:

1. Store the returned subscription state and invoice lists.
2. Update customer access according to the returned state.
3. Process the Fixed-price subscription webhooks when the operation sends one.
4. Retrieve the subscription after an ambiguous response before repeating the request.