> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create subscription > Create a new subscription. The subscription is typically returned in `incomplete` status; the customer must complete first-payment authorization via the returned `checkout_url` before the subscription transitions to `active` (or `trialing`). ## OpenAPI ````yaml /en/api/subscription-openapi.json post /api/v1/subscriptions/create openapi: 3.1.0 info: title: StablePay Subscription API version: '2026-04-20' summary: >- StablePay subscription endpoints: subscriptions, payment sessions, payment methods, refunds, and webhook events. description: >- OpenAPI specification for the StablePay subscription service. ## Basics - Base URL: `https://api.stablepay.co` - Prefix: `/api/v1` - Protocol: HTTPS - Format: JSON (UTF-8) ## Authentication All endpoints require `Authorization: Bearer {api_key}`. Write operations should also include replay-protection headers: `X-StablePay-Timestamp`, `X-StablePay-Nonce`, `X-StablePay-Signature`. ## Amount precision Amount fields are expressed in the smallest unit of the currency (e.g. `1999` represents $19.99 for USD; USDT/USDC use 6 decimal places). servers: - url: https://api.stablepay.co description: Production security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: Subscriptions description: Create, retrieve, list, and cancel subscriptions. paths: /api/v1/subscriptions/create: post: tags: - Subscriptions summary: Create subscription description: >- Create a new subscription. The subscription is typically returned in `incomplete` status; the customer must complete first-payment authorization via the returned `checkout_url` before the subscription transitions to `active` (or `trialing`). operationId: createSubscription parameters: - name: Idempotency-Key in: header required: true description: >- Merchant-generated idempotency key, up to 128 characters. Retrying with the same key returns the first created subscription. schema: type: string maxLength: 128 example: sub_create_20260430_0001 - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' example: items: - price_data: price_id: price_monthly_001 currency: USD product: Pro Plan unit_amount: 1999 recurring: interval: month quantity: 1 customer: cust_001 customer_email: alice@example.com customer_name: Alice currency: USD description: Pro Monthly Plan success_url: https://merchant.example/success cancel_url: https://merchant.example/cancel metadata: merchant_order_no: sub_order_1001 responses: '200': description: >- Subscription created. Reusing the same `Idempotency-Key` returns the first created subscription. content: application/json: schema: $ref: '#/components/schemas/Subscription' '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix timestamp in seconds. Must be within 5 minutes of server time. schema: type: string example: '1735689600' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request. schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed with the merchant API Secret. For GET requests, `requestBody` is an empty string. schema: type: string example: a1b2c3d4e5f6... schemas: CreateSubscriptionRequest: type: object required: - items - customer properties: items: type: array minItems: 1 maxItems: 1 description: Subscription items. Exactly one item is currently supported. items: $ref: '#/components/schemas/CreateSubscriptionItem' customer: type: string description: External customer ID from the merchant system. customer_email: type: string format: email description: Customer email. customer_phone: type: string description: Customer phone number. customer_name: type: string maxLength: 255 description: Customer name. currency: type: string enum: - USD - usd description: >- Subscription currency. Currently only `USD` is supported; can be omitted and derived from price_data.currency. description: type: string maxLength: 500 description: Subscription description. success_url: type: string maxLength: 512 description: >- Redirect URL after the initial payment succeeds. Maximum 512 characters. cancel_url: type: string maxLength: 512 description: >- Redirect URL after the initial payment is canceled. Maximum 512 characters. trial_end: type: integer format: int64 description: >- Trial end time, Unix seconds. Mutually exclusive with `billing_cycle_anchor`. billing_cycle_anchor: type: integer format: int64 description: >- Billing cycle anchor, Unix seconds. Mutually exclusive with `trial_end`; in non-trial scenarios it must be in the future, or now/past for immediate first charge. cancel_at: type: integer format: int64 description: >- Scheduled cancellation time, Unix seconds. Must be in the future and is mutually exclusive with `iterations`. iterations: type: integer minimum: 1 description: >- Automatically cancel after N billing cycles. Must be greater than 0 and is mutually exclusive with `cancel_at`. metadata: type: object additionalProperties: true description: Merchant metadata. Subscription: type: object description: Subscription object. properties: id: type: string description: Subscription ID. object: type: string example: subscription customer: type: string description: External customer ID. store_id: type: string description: Store ID. currency: type: string description: Currency. description: type: string description: Subscription description. status: $ref: '#/components/schemas/SubscriptionStatus' items: type: array items: $ref: '#/components/schemas/SubscriptionItem' description: Subscription items. payment_method_id: type: string description: Default payment method ID. billing_cycle_anchor: type: integer format: int64 description: Billing cycle anchor, Unix seconds. current_period_start: type: integer format: int64 description: Current period start, Unix seconds. current_period_end: type: integer format: int64 description: Current period end, Unix seconds. canceled_at: type: integer format: int64 description: Cancellation time, Unix seconds. cancel_at: type: integer format: int64 description: Scheduled cancellation time, Unix seconds. latest_invoice: type: string description: Latest invoice ID. latest_invoice_object: allOf: - $ref: '#/components/schemas/Invoice' description: Full invoice object returned when `expand=latest_invoice`. customer_object: allOf: - $ref: '#/components/schemas/Customer' description: Full customer object returned when `expand=customer`. payment_method_object: allOf: - $ref: '#/components/schemas/PaymentMethod' description: Full payment method object returned when `expand=payment_method`. checkout_url: type: string description: Initial-payment checkout URL, returned on creation. metadata: type: object additionalProperties: true description: Merchant metadata. created: type: integer format: int64 description: Creation time, Unix seconds. ErrorResponse: type: object description: Error response. properties: error: type: object properties: type: type: string description: Error type. code: type: string description: Error code. message: type: string description: Error message. param: type: string description: Related parameter. doc_url: type: string description: Error documentation URL. decline_code: type: string description: Decline code. request_log_url: type: string description: Request log URL. charge: type: string description: Related payment ID. request_id: type: string description: Request ID. timestamp: type: integer format: int64 description: Error timestamp in Unix seconds. CreateSubscriptionItem: type: object required: - price_data - quantity properties: price_data: $ref: '#/components/schemas/CreateSubscriptionPriceData' quantity: type: integer minimum: 1 description: >- Quantity. The current implementation does not apply a default, so it must be supplied and be at least 1. metadata: type: object additionalProperties: true description: Subscription item metadata. SubscriptionStatus: type: string enum: - incomplete - trialing - active - past_due - canceled - incomplete_expired description: Subscription status. SubscriptionItem: type: object properties: id: type: string description: Subscription item ID. price_data: $ref: '#/components/schemas/PriceData' quantity: type: integer minimum: 1 description: Quantity. metadata: type: object additionalProperties: true description: Subscription item metadata. Invoice: type: object required: - id - object - subscription_id - customer - amount_due - amount_paid - amount_remaining - currency - status - payment_status - billing_reason - period_start - period_end - created properties: id: type: string description: Invoice ID. object: type: string example: invoice subscription_id: type: string description: Related subscription ID. customer: type: string description: Customer ID. amount_due: type: integer format: int64 description: Amount due in minor units. amount_paid: type: integer format: int64 description: Amount paid in minor units. amount_remaining: type: integer format: int64 description: Amount remaining in minor units. currency: type: string description: Currency. status: $ref: '#/components/schemas/InvoiceStatus' payment_status: type: string enum: - pending - processing - completed - failed - canceled - expired description: Invoice payment status. billing_reason: type: string description: >- Billing reason, for example `subscription_create` or `subscription_cycle`. frequency: type: string description: Human-readable billing frequency, for example `Monthly`. recurring_interval: type: string enum: - day - week - month - year description: Recurring interval. recurring_interval_count: type: integer format: int32 description: Recurring interval count. period_start: type: integer format: int64 description: Billing period start, Unix seconds. period_end: type: integer format: int64 description: Billing period end, Unix seconds. payment_id: type: string description: >- Related payment session ID. The API prefers payment_session_id and falls back to trade_order_id. paid_at: type: integer format: int64 description: Payment completion time, Unix seconds. due_date: type: integer format: int64 description: Due date, Unix seconds. created: type: integer format: int64 description: Creation time, Unix seconds. Customer: type: object properties: id: type: string description: Customer ID. object: type: string example: customer merchant_id: type: string description: Merchant ID. external_customer_id: type: string description: External customer ID. email: type: string format: email description: Customer email. name: type: string description: Customer name. phone: type: string description: Customer phone number. default_payment_method: type: string description: Default payment method ID. description: type: string description: Customer description. created: type: integer format: int64 description: Creation time, Unix seconds. PaymentMethod: type: object properties: id: type: string description: Payment method ID. object: type: string example: payment_method customer: type: string description: Customer ID. merchant_id: type: string description: Merchant ID. type: type: string description: Payment method type. currency: type: string description: Currency. chain_type: type: integer format: int32 description: Chain type. status: type: string enum: - active - inactive - revoked - unknown description: Payment method status. mandate_id: type: string description: Mandate ID. metadata: type: object additionalProperties: true description: Metadata. created: type: integer format: int64 description: Creation time, Unix seconds. CreateSubscriptionPriceData: type: object required: - price_id - currency - product - unit_amount - recurring properties: price_id: type: string description: Price object ID. Required for business idempotency/identification. currency: type: string enum: - USD - usd description: Price currency. Currently only `USD` is supported. product: type: string description: Product ID or product name. Cannot be empty. unit_amount: type: integer format: int64 minimum: 1 description: Unit amount in minor units. Must be greater than 0. recurring: $ref: '#/components/schemas/CreateSubscriptionRecurringConfig' PriceData: type: object properties: id: type: string description: >- Price ID. This field is usually not returned by the current HTTP response. currency: type: string description: Currency. product: type: string description: Product ID or product name. unit_amount: type: integer format: int64 description: Unit amount in minor units. recurring: $ref: '#/components/schemas/RecurringConfig' InvoiceStatus: type: string enum: - open - paid - void description: Invoice status. CreateSubscriptionRecurringConfig: type: object required: - interval properties: interval: type: string enum: - day - week - month - year description: Billing interval. RecurringConfig: type: object properties: interval: type: string enum: - day - week - month - year description: Billing interval. interval_count: type: integer description: Billing interval count. Currently fixed to 1 by the server. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key, for example `Bearer sk_live_xxx`. stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix timestamp in seconds. Must be within 5 minutes of server time. stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request. stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed with the merchant API Secret. For GET requests, `requestBody` is an empty string. ````