Sign in
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"
  }
}

Changes

Changed in 1 of the 2 revisions of this API.7

  • 0e449a4e0dc87See the full diff
    • ○

      added the new optional request property canceledAt

      new-optional-request-property

    • ○

      added the new optional request property createdAt

      new-optional-request-property

    • ○

      added the new optional request property currentPeriodEnd

      new-optional-request-property

    • ○

      added the new optional request property externalId

      new-optional-request-property

    • ○

      added the new optional request property startDate

      new-optional-request-property

    • ○

      added the new optional request property status

      new-optional-request-property

    • ○

      added the media type application/json for the response with the status 201

      response-media-type-added