Sign in

v1

latestOpenAPI 3.0.1MIT2026-07-26336777.7 KB

post/subscription/create

Headers

Idempotency-Keystring

A unique key for making the request idempotent. Must match pattern: ^[a-zA-Z0-9\-_:\.]+$. See Idempotent Requests for more details.

Request body

amountinteger required

The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD)

currencystring required

Three letter abbreviation of the currency. Refer supported currencies

receiptIdstring

Your identifier of the order

callbackUrlstring required

The URL we will callback to with the order status once it finishes.

cancelUrlstring

The URL to redirect the customer to when they cancel the subscription. If not provided, the callbackUrl will be used as fallback.

interval'DAY' | 'WEEK' | 'MONTH' | 'YEAR' required

The interval group between subscriptions.

intervalCountinteger required

The number of intervals between subscription billings. For example, interval = MONTH and intervalCount = 3 bills every 3 months.

cycleCountinteger required

The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count.

upfrontAmountinteger

An optional amount that merchants can set to be charged to the customer at the time the subscription is activated. This amount replaces the first billing cycle charge — the regular subscription amount is not added on top of it. Regular billing resumes from the next cycle.

The amount is in the lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (minimum amount should be greater than 1 USD).

Validation Rules:

  • Not compatible with trialPeriodCount and trialPeriodInterval — cannot be provided simultaneously
trialPeriodCountinteger

The number of trial periods before the first billing cycle. Must be greater than or equal to 0 if provided.

Validation Rules:

  • If trialPeriodCount is provided, trialPeriodInterval must also be provided
  • trialPeriodCount is not compatible with upfrontAmount - both cannot be provided simultaneously
trialPeriodInterval'DAY' | 'WEEK' | 'MONTH' | 'YEAR'

The interval for the trial period.

Validation Rules:

  • Required when trialPeriodCount is provided
metadataobject

A collection of key-value pairs that can be attached to an object for storing additional structured information. This is useful for capturing custom data or context-specific attributes.

Constraints:

  • Maximum of 50 key-value pairs allowed.
  • Each key must be no longer than 40 characters.
  • Each value must be a string and cannot exceed 500 characters.
phoneNumberRequiredboolean

Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.

customerIdstring

The unique identifier for the customer, generated via the create-customer API. This can be used to associate the payment with a specific customer in your system.

Example request

{
  "amount": 100,
  "currency": "USD",
  "receiptId": "order123",
  "customerDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "contactNumber": "+919123456789",
    "customerAddress": {
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 1",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "postalCode": "2424"
    }
  },
  "callbackUrl": "https://example.com/callback",
  "cancelUrl": "https://example.com/cancel",
  "interval": "MONTH",
  "intervalCount": 2,
  "cycleCount": 2,
  "upfrontAmount": 200,
  "trialPeriodCount": 7,
  "trialPeriodInterval": "DAY",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  },
  "customerId": "cus_Tfd3Jq1tZxPjYVhRQW2r3",
  "productPage": {
    "name": "Premium Subscription",
    "description": "Access to premium features and content"
  }
}

Response

Create Subscription response

subscriptionIdstring

Unique identifier of the subscription

createdAtstring date-time

Timestamp of when the subscription was created

fwdUrlstring

The URL to redirect the customer to the xPay payment gateway for payment.

Example response

{
  "subscriptionId": "sub_fooBOwYsaK50AEfK",
  "createdAt": "2024-09-26T10:41:50.472+00:00",
  "fwdUrl": "https://pay.xpaycheckout.com/?subscription_id=67f53a6e2097773e4f0112c8"
}