> ## Documentation Index > Fetch the complete documentation index at: https://docs.xpaycheckout.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Subscription ## OpenAPI ````yaml POST /subscription/create openapi: 3.0.1 info: title: xPay API Store description: '' license: name: MIT version: 1.0.0 servers: - url: https://api.xpaycheckout.com security: - basicAuth: [] paths: /subscription/create: post: parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: description: Create Subscription content: application/json: schema: $ref: '#/components/schemas/create-subscription' required: true responses: '200': description: Create Subscription response content: application/json: schema: $ref: '#/components/schemas/create-subscription-response' '400': description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 pattern: ^[a-zA-Z0-9\-_:\.]+$ description: >- A unique key for making the request idempotent. Must match pattern: `^[a-zA-Z0-9\-_:\.]+$`. See [Idempotent Requests](/developer-resources/idempotency) for more details. example: KG5LxwFBepaKHyUD schemas: create-subscription: required: - amount - currency - customerDetails - callbackUrl - interval - intervalCount - cycleCount type: object properties: amount: description: >- 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) type: integer format: int64 example: 100 currency: type: string description: >- Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported) example: USD receiptId: type: string description: Your identifier of the order example: order123 customerDetails: $ref: '#/components/schemas/BillingDetails' callbackUrl: description: The URL we will callback to with the order status once it finishes. type: string example: https://example.com/callback cancelUrl: description: >- The URL to redirect the customer to when they cancel the subscription. If not provided, the callbackUrl will be used as fallback. type: string example: https://example.com/cancel interval: type: string description: The interval group between subscriptions. enum: - DAY - WEEK - MONTH - YEAR example: MONTH intervalCount: type: integer description: >- The number of intervals between subscription billings. For example, `interval = MONTH` and `intervalCount = 3` bills every 3 months. format: int64 example: 2 cycleCount: type: integer description: >- The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count. format: int64 example: 2 upfrontAmount: $ref: '#/components/schemas/UpfrontAmount' trialPeriodCount: type: integer format: int64 description: >- 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 minimum: 0 example: 7 trialPeriodInterval: type: string description: |- The interval for the trial period. **Validation Rules:** - Required when `trialPeriodCount` is provided enum: - DAY - WEEK - MONTH - YEAR example: DAY metadata: type: object description: >- 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. additionalProperties: type: string example: orderId: '12345' customerNote: Deliver after 5 PM phoneNumberRequired: type: boolean description: >- Flag to indicate whether phone number is required from the customer during checkout. By default, this is false. example: false customerId: $ref: '#/components/schemas/CustomerId' productPage: $ref: '#/components/schemas/ProductPage' description: Product Page - showcases more about the product on the checkout page create-subscription-response: type: object properties: subscriptionId: type: string description: Unique identifier of the subscription example: sub_fooBOwYsaK50AEfK createdAt: type: string format: date-time description: Timestamp of when the subscription was created example: '2024-09-26T10:41:50.472+00:00' fwdUrl: type: string description: >- The URL to redirect the customer to the xPay payment gateway for payment. example: >- https://pay.xpaycheckout.com/?subscription_id=67f53a6e2097773e4f0112c8 Error: required: - errorCode - errorDescription type: object properties: errorCode: type: string example: bad_request errorDescription: type: string example: Failed to read request BillingDetails: type: object description: Billing details for the customer. required: - name - email - contactNumber properties: name: type: string description: Customer's name example: John Doe email: type: string description: Customer's email address example: john.doe@example.com contactNumber: type: string description: >- Customer's contact number ([E.164 format](https://en.wikipedia.org/wiki/E.164)), including the country code (e.g., +1 for US, +44 for UK, +91 for India). example: '+919123456789' customerAddress: $ref: '#/components/schemas/CustomerAddress' UpfrontAmount: type: integer format: int64 description: >- 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 minimum: 1 example: 200 CustomerId: type: string description: >- The unique identifier for the customer, generated via the [create-customer API](/developer-resources/endpoints/customer/create-customer). This can be used to associate the payment with a specific customer in your system. example: cus_Tfd3Jq1tZxPjYVhRQW2r3 ProductPage: type: object required: - name properties: name: type: string description: Product name. Must be between 2 and 100 characters long. minLength: 2 maxLength: 100 example: Premium Subscription description: type: string description: Product description. Must be less than 500 characters long. maxLength: 500 example: Access to premium features and content CustomerAddress: type: object properties: addressLine1: type: string description: Line 1 of the customer's address example: 123 Main St addressLine2: type: string description: Line 2 of the customer's address example: Apt 1 city: type: string description: City of the customer's address example: New York state: type: string description: State of the customer's address example: NY country: type: string description: >- Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). example: US postalCode: type: string description: Postal code example: '2424' securitySchemes: basicAuth: type: http scheme: basic ````