Create Subscription
POST/subscriptionsDescription
Create a new subscription for recurring stablecoin billing. Returns a subscription object containing a checkout_url where the customer must complete the initial payment and authorize future charges from their wallet.
💳
The first payment is collected when the customer completes the checkout. Subsequent payments are initiated automatically based on the billing interval using the customer’s authorized wallet.
Headers
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your API key | yes |
| Content-Type | application/json | yes |
Request Body
| Name | Type | Description | Required |
|---|---|---|---|
| amount | number | Recurring payment amount in the smallest currency unit. | yes |
| currency | string | Three-letter ISO currency code for pricing (e.g., "USD", "EUR"). | yes |
| interval | string | Billing interval: "weekly", "monthly", or "yearly". | yes |
| name | string | Name of the subscription plan shown to the customer. | yes |
| description | string | Description of the subscription plan. | no |
| success_url | string | URL to redirect after successful subscription creation. | yes |
| cancel_url | string | URL to redirect if the customer cancels. | no |
| customer_email | string | Customer email for payment receipts. | no |
| trial_days | number | Number of days for a free trial before billing starts. | no |
| metadata | object | Custom key-value pairs to attach to the subscription. | no |
| payment_mode | string | Payment mode: "direct" (funds sent directly to your settlement wallet) or "two_step" (funds held for capture/refund via signed requests). Defaults to "direct". | no |
Example Request
const response = await fetch('https://checkout.exodus.com/subscriptions', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 2999,
currency: 'USD',
interval: 'monthly',
name: 'Pro Plan',
description: 'Access to all premium features',
payment_mode: 'two_step',
success_url: 'https://yoursite.com/subscription/success',
cancel_url: 'https://yoursite.com/subscription/cancel',
customer_email: '[email protected]',
trial_days: 14,
metadata: {
plan_id: 'pro_monthly',
user_id: 'usr_12345',
},
}),
});Response
SUCCESSFUL SUBSCRIPTION CREATION
{
"id": "sub_1234567890abcdef",
"object": "subscription",
"amount": 2999,
"currency": "USD",
"interval": "monthly",
"name": "Pro Plan",
"description": "Access to all premium features",
"payment_mode": "two_step",
"status": "pending",
"checkout_url": "https://checkout.exodus.com/subscribe/sub_1234567890abcdef",
"success_url": "https://yoursite.com/subscription/success",
"cancel_url": "https://yoursite.com/subscription/cancel",
"customer_email": "[email protected]",
"trial_days": 14,
"trial_ends_at": "2024-01-29T12:00:00Z",
"current_period_start": null,
"current_period_end": null,
"metadata": {
"plan_id": "pro_monthly",
"user_id": "usr_12345"
},
"created_at": "2024-01-15T12:00:00Z"
}Error Responses
VALIDATION ERROR
{
"error": {
"type": "validation_error",
"message": "Invalid interval. Must be one of: weekly, monthly, yearly",
"param": "interval"
}
}