Create a fixed-price subscription

Create a subscription after you create a plan and collect a reusable payment token through the XPay Element.

Use the XPay API reference for the canonical subscription creation endpoint, required fields, and response schema.

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

Create the subscription#

The request uses:

• plan_id: The plan the customer selected.
• payment.token: The token delivered through the verified payment webhook at token.id.
• start_date: The current or future date on which subscription billing begins.
• timezone: The timezone used for the subscription schedule.
• collect_advance: Whether XPay attempts payment during subscription creation.
• failure_action: What XPay does if an advance payment fails. This applies only when collect_advance is true.

{
  "plan_id": "{{plan_id}}",
  "payment": {
    "token": "{{payment_token_from_webhook}}"
  },
  "start_date": "{{iso_8601_start_date}}",
  "timezone": "Asia/Karachi",
  "collect_advance": false
}

For collect_advance: false, the response returns the created subscription without attempting payment:

{
  "success": true,
  "responseStatus": "OK",
  "message": "The subscription has been successfully created with id xpay_subs_{{subscription_id}}",
  "data": {
    "subscription_id": "xpay_subs_{{subscription_id}}",
    "plan_id": "xpay_plan_{{plan_id}}",
    "state": "draft",
    "active": true,
    "start_date": "2026-08-01T00:00:00.000Z",
    "timezone": "Asia/Karachi",
    "collect_advance": false,
    "billing_cycle": {
      "interval": "month",
      "every": 1
    },
    "payment": {
      "amount": 5000,
      "currency": "PKR",
      "token_type": "card"
    },
    "scheduled_invoices": [
      {
        "invoice_id": "xpay_invoice_{{invoice_id}}",
        "date": "2026-08-01T00:00:00.000Z"
      }
    ]
  }
}

The response is shortened and omits the reusable payment token. XPay amounts use major currency units and support up to two decimal places; 5000 with PKR represents PKR 5,000.00.

Choose initial payment behavior#

collect_advance controls whether XPay attempts payment while creating the subscription.

failure_action affects creation when advance collection fails:

Use a future start date#

Supply a future start_date when the merchant wants to create the subscription now and start billing later.

This supports use cases such as:

• Delayed subscription activation
• A subscription that begins after an onboarding period
• A future service commencement date

When collect_advance is false, XPay does not collect payment during creation and follows the invoice schedule beginning on start_date.

Plans with a billing-cycle anchor#

If the selected plan contains billing_cycle_anchor_config, use the plan's calendar schedule when calculating recurring invoice dates.

• With collect_advance: true, XPay attempts the prorated amount for the remainder of the current anchored cycle. The next recurring invoice uses the next anchor date.
• With collect_advance: false, XPay doesn't attempt an initial payment. The first scheduled invoice uses the next anchor date.

XPay interprets start_date and the subscription schedule using the request's timezone.

Store the result#

Store:

• Subscription ID
• Subscription state
• Plan ID
• Payment token reference
• Scheduled invoice IDs
• First scheduled invoice date

XPay can reserve scheduled invoice IDs before the corresponding invoice objects are created. Use the Invoices and recurring payments or invoice screen to retrieve the current invoice object and state.

Handle a failed advance payment#

If failure_action is CONTINUE, XPay creates the subscription with draft state. Store and reconcile the returned subscription ID before deciding whether to retry payment or perform another supported merchant action.

Don't repeat the request after an uncertain response without first checking whether XPay created the subscription.