Sign in

v2

latestOpenAPI 3.0.0raw.githubusercontent.com2026-02-16143114179.4 KB
Subscriptions

Create a new subscription

Subscribe a customer to a plan. The plan must have a price matching the specified currency. Optionally set a trial period in days.

post/api/subscriptions

Request body

customerIdstring required

Customer ID

planIdstring required

Plan ID

currencystring required

Currency for billing

trialDaysnumber

Number of trial days

metadataobject
startDatestring

Override subscription start date (ISO 8601). Defaults to now.

currentPeriodEndstring

Override current period end (ISO 8601). Defaults to calculated from startDate + billing interval.

status'ACTIVE' | 'TRIALING' | 'PAUSED' | 'PAST_DUE' | 'CANCELED'

Override subscription status for imports

createdAtstring

Backdate createdAt (ISO 8601). For data imports.

externalIdstring

External ID for linking to external systems

canceledAtstring

Canceled at date (ISO 8601). For importing canceled subscriptions.

Example request

{
  "currency": "NGN",
  "trialDays": 14
}

Response

Subscription created (status: ACTIVE or TRIALING)

idstring required
externalIdstring
customerIdstring required
planIdstring required
previousPlanIdstring
status'ACTIVE' | 'PAST_DUE' | 'CANCELED' | 'TRIALING' | 'PAUSED' required
currencystring required
billingTiming'IN_ADVANCE' | 'IN_ARREARS' required
currentPeriodStartstring required
currentPeriodEndstring required
cancelAtstring
canceledAtstring
trialStartstring
trialEndstring
startedAtstring required
metadataobject
createdAtstring required
updatedAtstring required

Example response

{
  "id": "clx1234567890",
  "externalId": "ext_sub_123",
  "customerId": "clxcust123",
  "planId": "clxplan123",
  "status": "ACTIVE",
  "currency": "USD",
  "billingTiming": "IN_ARREARS",
  "customer": {
    "id": "clx1234567890",
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "plan": {
    "id": "clxplan123",
    "name": "Premium Monthly",
    "billingInterval": "MONTHLY"
  }
}