Sign in

v1

latestOpenAPI 3.1.02026-07-24104338.0 KB
Subscriptions

Create a subscription

Subscribes a subscriber (by email) to one of your plans. Starts in PENDING until the subscriber completes checkout. Pass customerProfile to supply Travel Rule / AML customer data.

post/api/v3/subscriptions

Request body

planIdstring uuid required
amountstring

Per-subscription amount (value only; asset comes from the plan). Required when the plan is VARIABLE; must be omitted when the plan is FIXED.

notifyUrlstring uri

Webhook URL (http/https, max 2048 chars) for lifecycle and payment events.

returnUrlstring uri

Where the subscriber is redirected after completing or exiting checkout (http/https, max 2048 chars).

Example request

{
  "amount": "49.00"
}

Response

Subscription created.

idstring uuid required
planIdstring uuid required
planNamestring required

Current name of the plan.

customerProfileIdstring nullable

Your customer profile id, as supplied at creation (customerProfile.profileId).

emailstring email nullable

Subscriber's email address. Null when the subscriber has no email on file.

notifyUrlstring uri nullable

Webhook URL for lifecycle and payment events, as supplied at creation.

returnUrlstring uri nullable

Where the subscriber is redirected after checkout, as supplied at creation.

checkoutUrlstring uri nullable

Hosted checkout link to send the subscriber to. Present while the subscription is awaiting checkout (PENDING); null once checkout is complete or no longer applicable.

status'PENDING' | 'TRIALING' | 'ACTIVE' | 'PAST_DUE' | 'CANCELED' | 'EXPIRED' required

Subscription lifecycle state. PENDING — created; awaiting subscriber checkout. TRIALING — in a trial period before the first charge. ACTIVE — checkout complete; billing on schedule. PAST_DUE — a charge failed; retrying within the grace period before a terminal state. CANCELED — stopped before its natural end (see cancelReason). EXPIRED — ended naturally or after retries were exhausted (see expiryReason).

startDateinteger

Unix epoch seconds.

cycleNumberinteger required

How many billing cycles have started.

nextPaymentDateinteger

Unix epoch seconds.

endsAtinteger

Unix epoch seconds.

createdAtinteger required

Unix epoch seconds.

updatedAtinteger required

Unix epoch seconds.

Example response

{
  "amount": {
    "amount": "29.00",
    "asset": "USD"
  },
  "startDate": 1748513400,
  "currentPeriod": {
    "start": 1748513400,
    "end": 1748513400
  },
  "nextPaymentDate": 1748513400,
  "endsAt": 1748513400,
  "cancellation": {
    "at": 1748513400
  },
  "expiration": {
    "at": 1748513400
  },
  "createdAt": 1748513400,
  "updatedAt": 1748513400
}