Skip to main content
POST
/
api
/
v1
/
subscriptions
/
create
{
  "id": "<string>",
  "object": "subscription",
  "customer": "<string>",
  "store_id": "<string>",
  "currency": "<string>",
  "description": "<string>",
  "status": "incomplete",
  "items": [
    {
      "id": "<string>",
      "price_data": {
        "id": "<string>",
        "currency": "<string>",
        "product": "<string>",
        "unit_amount": 123,
        "recurring": {
          "interval": "day",
          "interval_count": 123
        }
      },
      "quantity": 2,
      "metadata": {}
    }
  ],
  "payment_method_id": "<string>",
  "billing_cycle_anchor": 123,
  "current_period_start": 123,
  "current_period_end": 123,
  "canceled_at": 123,
  "cancel_at": 123,
  "latest_invoice": "<string>",
  "latest_invoice_object": {
    "id": "<string>",
    "object": "invoice",
    "subscription_id": "<string>",
    "customer": "<string>",
    "amount_due": 123,
    "amount_paid": 123,
    "amount_remaining": 123,
    "currency": "<string>",
    "status": "open",
    "payment_status": "pending",
    "billing_reason": "<string>",
    "period_start": 123,
    "period_end": 123,
    "created": 123,
    "frequency": "<string>",
    "recurring_interval": "day",
    "recurring_interval_count": 123,
    "payment_id": "<string>",
    "paid_at": 123,
    "due_date": 123
  },
  "customer_object": {
    "id": "<string>",
    "object": "customer",
    "merchant_id": "<string>",
    "external_customer_id": "<string>",
    "email": "jsmith@example.com",
    "name": "<string>",
    "phone": "<string>",
    "default_payment_method": "<string>",
    "description": "<string>",
    "created": 123
  },
  "payment_method_object": {
    "id": "<string>",
    "object": "payment_method",
    "customer": "<string>",
    "merchant_id": "<string>",
    "type": "<string>",
    "currency": "<string>",
    "chain_type": 123,
    "status": "active",
    "mandate_id": "<string>",
    "metadata": {},
    "created": 123
  },
  "checkout_url": "<string>",
  "metadata": {},
  "created": 123
}

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.

Authorizations

Authorization
string
header
required

Bearer API Key, for example Bearer sk_live_xxx.

X-StablePay-Timestamp
string
header
required

Unix timestamp in seconds. Must be within 5 minutes of server time.

X-StablePay-Nonce
string
header
required

Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.

X-StablePay-Signature
string
header
required

Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.

Headers

Idempotency-Key
string
required

Merchant-generated idempotency key, up to 128 characters. Retrying with the same key returns the first created subscription.

Maximum string length: 128
X-StablePay-Timestamp
string
required

Unix timestamp in seconds. Must be within 5 minutes of server time.

X-StablePay-Nonce
string
required

Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.

Required string length: 16 - 64
X-StablePay-Signature
string
required

Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.

Body

application/json
items
object[]
required

Subscription items. Exactly one item is currently supported.

Required array length: 1 element
customer
string
required

External customer ID from the merchant system.

customer_email
string<email>

Customer email.

customer_phone
string

Customer phone number.

customer_name
string

Customer name.

Maximum string length: 255
currency
enum<string>

Subscription currency. Currently only USD is supported; can be omitted and derived from price_data.currency.

Available options:
USD,
usd
description
string

Subscription description.

Maximum string length: 500
success_url
string

Redirect URL after the initial payment succeeds. Maximum 512 characters.

Maximum string length: 512
cancel_url
string

Redirect URL after the initial payment is canceled. Maximum 512 characters.

Maximum string length: 512
trial_end
integer<int64>

Trial end time, Unix seconds. Mutually exclusive with billing_cycle_anchor.

billing_cycle_anchor
integer<int64>

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
integer<int64>

Scheduled cancellation time, Unix seconds. Must be in the future and is mutually exclusive with iterations.

iterations
integer

Automatically cancel after N billing cycles. Must be greater than 0 and is mutually exclusive with cancel_at.

Required range: x >= 1
metadata
object

Merchant metadata.

Response

Subscription created. Reusing the same Idempotency-Key returns the first created subscription.

Subscription object.

id
string

Subscription ID.

object
string
Example:

"subscription"

customer
string

External customer ID.

store_id
string

Store ID.

currency
string

Currency.

description
string

Subscription description.

status
enum<string>

Subscription status.

Available options:
incomplete,
trialing,
active,
past_due,
canceled,
incomplete_expired
items
object[]

Subscription items.

payment_method_id
string

Default payment method ID.

billing_cycle_anchor
integer<int64>

Billing cycle anchor, Unix seconds.

current_period_start
integer<int64>

Current period start, Unix seconds.

current_period_end
integer<int64>

Current period end, Unix seconds.

canceled_at
integer<int64>

Cancellation time, Unix seconds.

cancel_at
integer<int64>

Scheduled cancellation time, Unix seconds.

latest_invoice
string

Latest invoice ID.

latest_invoice_object
object

Full invoice object returned when expand=latest_invoice.

customer_object
object

Full customer object returned when expand=customer.

payment_method_object
object

Full payment method object returned when expand=payment_method.

checkout_url
string

Initial-payment checkout URL, returned on creation.

metadata
object

Merchant metadata.

created
integer<int64>

Creation time, Unix seconds.

Last modified on April 30, 2026