Fixed-price subscription quickstart

Create LedgerPro Basic and subscribe a customer without collecting an advance payment. Use the XPay API reference for canonical endpoint schemas.

What you'll create#

This quickstart creates:

• A LedgerPro Basic product priced at PKR 5,000.00.
• A monthly fixed-price plan.
• A subscription with collect_advance: false.
• A draft subscription and its first scheduled invoice ID.

1. Prepare the subscription inputs#

Before starting, obtain the XPay credentials and reusable payment token required by the subscription creation API. Use Collect a payment token with XPay Element and Integrate XPay webhooks for those integration flows.

2. Create a product#

Create LedgerPro Basic at PKR 5,000.00 per month and store the returned product ID.

POST {{base_url}}/public/v1/product

{
  "name": "LedgerPro Basic",
  "description": "Monthly access to LedgerPro Basic",
  "price": 5000,
  "currency": "PKR",
  "active": true
}

XPay generates the product ID unless the merchant supplies an id. Store the returned product_id for the plan request:

{
  "success": true,
  "data": {
    "product_id": "xpay_product_{{product_id}}",
    "name": "LedgerPro Basic",
    "price": 5000,
    "currency": "PKR",
    "active": true
  }
}

3. Create a fixed-price plan#

Create the LedgerPro Basic monthly plan. It references the product, bills every month, and anchors renewal to the first day of the month.

POST {{base_url}}/public/v1/plan

{
  "name": "LedgerPro Basic monthly",
  "interval": "month",
  "every": 1,
  "billing_cycle": "per_unit/user",
  "billing_cycle_anchor_config": {
    "day_of_month": 1
  },
  "product": [
    {
      "product_id": "{{product_id}}",
      "quantity": 1
    }
  ],
  "active": true
}

Because the request doesn't override amount and currency, XPay derives PKR 5,000.00 from the product. Store the returned plan_id:

{
  "success": true,
  "data": {
    "plan_id": "xpay_plan_{{plan_id}}",
    "name": "LedgerPro Basic monthly",
    "amount": 5000,
    "currency": "PKR",
    "interval": "month",
    "every": 1,
    "active": true
  }
}

4. Use the payment token#

Use the reusable token delivered by XPay at token.id. The subscription creation request sends this value as payment.token.

5. Create the subscription#

Create the subscription from the merchant backend using the documented XPay API endpoint and fields, including:

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

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

This quickstart uses collect_advance: false. XPay creates the subscription without attempting payment and schedules the first invoice from the applicable start date or billing anchor.

See Create a fixed-price subscription when the merchant needs advance collection or a different failure action.

6. Store the result#

The API returns the created subscription in data:

{
  "success": true,
  "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,
    "scheduled_invoices": [
      {
        "invoice_id": "xpay_invoice_{{invoice_id}}",
        "date": "2026-08-01T00:00:00.000Z"
      }
    ]
  }
}

The response is shortened to the fields used in this flow. See Create a fixed-price subscription for the other initial-collection outcomes and schedule behavior.

Store:

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

7. Process subscription events#

Use Fixed-price subscription webhooks to handle later billing outcomes and lifecycle changes. Keep subscription and invoice states separate, as described in Subscription lifecycle and statuses.

Next steps#

• Review Create a fixed-price subscription for advance collection, failure handling, and start-date behavior.
• Review Invoices and recurring payments to understand scheduled invoice IDs and invoice payment attempts.
• Review Failed payments and retries before enabling recurring billing in production.