Create a usage-based subscription

Create a usage-based subscription after configuring the product, billing meters, pricing models, plan, and payment token.

Before you begin#

You need:

• An active usage-based plan with a non-empty pricing_models array.
• A reusable payment token received from the verified XPay webhook at token.id, or an XPay customer with an enabled default payment method.
• A current or future start_date.
• A supported timezone.

Create the subscription#

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

{
  "plan_id": "{{usage_plan_id}}",
  "payment": {
    "token": "{{payment_token_from_webhook}}"
  },
  "start_date": "{{iso_8601_start_date}}",
  "timezone": "Asia/Karachi",
  "collect_advance": false,
  "metadata": {
    "merchant_customer_id": "customer-1001"
  }
}

The response returns the created usage-based subscription in data:

{
  "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,
    "is_usage_based": true,
    "subscription_type": "one-time",
    "start_date": "2026-08-01T00:00:00.000Z",
    "timezone": "Asia/Karachi",
    "collect_advance": false,
    "billing_cycle": {
      "interval": "month",
      "every": 1
    },
    "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.

Set payment.token to the reusable token delivered by the verified webhook at token.id.

The first billing date follows the subscription's start_date and the plan's billing-cycle anchor rules.

The subscription can accept meter events while it is eligible to receive usage. Events are rejected when the subscription is inactive, paused, or cancelled.

Store the response#

Store:

• Subscription ID and state
• Plan ID
• Scheduled invoice IDs and dates
• Start date and timezone
• The merchant's payment-token reference

Use the subscription ID when reporting usage and managing the subscription lifecycle.

Begin reporting usage#

Use Meter events to begin reporting usage and Usage aggregation and invoice generation to reconcile billed amounts. Usage-based subscriptions use the same Manage a fixed-price subscription and Invoices and recurring payments operations as fixed-price subscriptions unless a page states otherwise.