Create a subscription checkout

POST/subscription-checkouts

Create a single-use intent that authorizes a customer to start a recurring subscription. The merchant declares an optional per-window budget (defaults to 10x price) and an optional per-charge cap (defaults to budget); all amounts are in price_currency's minor units. The subscriber picks the settlement token at subscribe time. Returns a checkout_url — redirect the customer there to complete the subscribe and first-charge flow. No signed request is needed at creation; the customer's on-chain signature authorizes the subscription and first charge atomically.

Headers

Header	Description	Required
Authorization	Bearer token with your secret API key	yes

Request Body

Field	Type	Required	Description
supported_chains	string[]	—
price	string	yes	The recurring per-cycle amount, in price_currency's ISO 4217 minor units (e.g. cents for USD, centavos for ARS; CLP has no minor unit, so CLP 15,000 is 15000). At most 9007199254740991.
price_currency	enum: USD \| ARS \| BRL \| COP \| UYU \| CLP \| VES \| MXN \| BOB \| EUR	yes	Required ISO-4217 pricing currency; price, cap, and budget are all denominated in its minor units. Crypto-settled businesses price in USD and ARS, and test businesses also in BRL, COP, UYU, CLP, VES, MXN and BOB. Fiat-settled businesses price in their settlement currency. The subscriber picks the settlement token and chain at subscribe time.
period_duration	integer	yes
cap	string	—	Per-charge ceiling, in price_currency's minor units. Optional -- defaults to budget (provided or derived). At most 9007199254740991.
budget	string	—	Per-window spend ceiling, in price_currency's minor units. Optional -- defaults to 10x price. At most 9007199254740991.
initial_charge	boolean	—	Whether the customer is charged the first period at subscribe time. When false, the subscribe signature only registers the subscription on-chain (no funds move) and billing starts with the first merchant-relayed charge. Chargeless subscriptions are EVM-only: when supported_chains is omitted, chains without chargeless subscribe support are dropped from the resolved set; naming one explicitly in supported_chains is rejected, as is a merchant with no chargeless-capable deployment at all.
subscriber	string	—
external_customer_id	string	—
success_url	string	—	Where to redirect the subscriber after a successful subscribe. Automatic countdown redirect and the primary CTA on the completed screen.
cancel_url	string	—	Where to redirect the subscriber if the subscription checkout was actually cancelled. Also used on the expired terminal screen.
return_url	string	—	Where to send the subscriber if they leave a still-pending subscription checkout. Purely navigational — no side effects. Distinct from cancel_url (the subscription checkout was actually cancelled) and success_url (the post-subscribe confirmation destination).
metadata	object	—	Flat map of merchant-defined references. Up to 50 keys; keys up to 40 characters; values are strings up to 500 characters (nested values are rejected). Echoed back on the intent and on every `subscription_checkout.` webhook. Two keys are also rendered on the hosted subscribe page: `plan_name` at the end of the summary card, below the economic terms, with `plan_description` as supporting copy directly beneath it. Only those two exact keys are read — every other key, including any other `plan_` key, stays opaque to Exodus and is never shown. The two are independent: pass one, both, or neither.
expires_at	string · date-time	—

Example Request

Request

const response = await fetch('https://checkout-api.exodus.com/subscription-checkouts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "supported_chains": [
      "eip155:1",
      "eip155:137"
    ],
    "price": "250000",
    "price_currency": "ARS",
    "period_duration": 2592000,
    "cap": "1000000",
    "budget": "2500000",
    "initial_charge": true,
    "success_url": "https://merchant.com/subscribed",
    "cancel_url": "https://merchant.com/cancelled",
    "return_url": "https://merchant.com/plans/pro",
    "metadata": {
      "external_plan_ref": "pro_monthly",
      "plan_name": "Pro",
      "plan_description": "Unlimited projects and priority support"
    }
  }),
});

Responses

Status	Description
201	The created subscription checkout.
400	Validation error
401	Missing or invalid authentication
403	API key lacks the required scope

Response body

Field	Type	Required	Description
object	enum: subscription_checkout	yes
id	string	yes
status	enum: pending \| completed \| expired \| cancelled	yes
onchain_id	string	yes
subscription_id	string \| null	yes	The on-chain id of the subscription created from this checkout, usable with GET /subscriptions/{id}, or null until one exists. Always equal to onchain_id once a subscription is bound: onchain_id is reserved when the checkout is created, so subscription_id is the field that tells you a subscription exists. Present even when the checkout is cancelled or expired, because a subscriber whose subscribe landed after a cancel keeps a live subscription.
business_id	string	yes	Your Exodus business id. Stable for the life of the business and also returned by GET /settings.
business_name	string	yes	The merchant name shown to subscribers on the hosted subscribe page: your display_name from GET /settings when set, otherwise your registered business name.
background_color	string \| null	yes
primary_color	string \| null	yes
subscriber	string \| null	yes
external_customer_id	string \| null	yes
subscription_options	object[]	yes	Every chain/token combination the subscriber may pick at subscribe time. Always an array -- do not assume a single entry.
price	string	yes	The recurring per-cycle amount, in price_currency's minor units. price, cap, and budget share one unit system; fiat figures convert to exact-out token amounts at subscribe/charge time via a quote, never pre-converted here. At most 9007199254740991.
price_currency	string \| null	yes	ISO-4217 pricing currency. Always set on checkouts created after fiat-only creation shipped; null only on legacy rows.
period_duration	number	yes
cap	string \| null	yes	Per-charge ceiling, same unit system as price.
budget	string	yes	Per-window spend ceiling, same unit system as price.
initial_charge	boolean	yes
checkout_url	string	yes
success_url	string \| null	yes
cancel_url	string \| null	yes
return_url	string \| null	yes
metadata	object \| null	yes
expires_at	string	yes
created_at	string	yes
updated_at	string	yes
completed_at	string \| null	yes
cancelled_at	string \| null	yes
expired_at	string \| null	yes
cancellation_reason	string \| null	yes

subscription_options

Field	Type	Required
chain	string	yes
token	string	yes
subscription_manager_address	string	yes
relayer_address	string	yes

Example Response

{
  "object": "subscription_checkout",
  "id": "schk_1234567890abcdef",
  "status": "completed",
  "onchain_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
  "subscription_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
  "business_id": "clzk3n8x50000qw3f7h2p9r1b",
  "business_name": "Acme Inc",
  "background_color": "#0f172a",
  "primary_color": "#7c3aed",
  "subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
  "external_customer_id": "cus_42",
  "subscription_options": [
    {
      "chain": "eip155:1",
      "token": "USDC",
      "subscription_manager_address": "0xa1b2c3d4e5f6789012345678901234567890abcd",
      "relayer_address": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b"
    },
    {
      "chain": "eip155:137",
      "token": "USDC",
      "subscription_manager_address": "0xb2c3d4e5f67890123456789012345678901234cd",
      "relayer_address": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b"
    }
  ],
  "price": "250000",
  "price_currency": "ARS",
  "period_duration": 2592000,
  "cap": "1000000",
  "budget": "2500000",
  "initial_charge": true,
  "checkout_url": "https://checkout.exodus.com/subscribe/schk_1234567890abcdef",
  "success_url": "https://merchant.com/subscribed",
  "cancel_url": "https://merchant.com/cancelled",
  "return_url": "https://merchant.com/plans/pro",
  "metadata": {
    "external_plan_ref": "pro_monthly",
    "plan_name": "Pro",
    "plan_description": "Unlimited projects and priority support"
  },
  "expires_at": "2026-05-19T12:05:00Z",
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:02:18Z",
  "completed_at": "2026-05-19T12:02:18Z",
  "cancelled_at": null,
  "expired_at": null,
  "cancellation_reason": null
}

Error Response

Error (e.g. 400)

{
  "error": {
    "type": "validation_error",
    "message": "amount must be a positive number",
    "param": "amount"
  }
}

List subscription checkouts Retrieve a subscription checkout