Subscriptions API

The Subscriptions API lets you build recurring billing relationships with your customers. You can charge customers on a recurring schedule (daily, weekly, monthly, yearly), offer free trials, pause memberships, and handle cancellations.

Subscription Lifecycle & States

A subscription automatically compiles and sends invoices to the associated customer at the start of each billing period. Subscriptions can progress through the following statuses:

Status	Description
`INCOMPLETE`	Subscription is created, but the initial invoice is unpaid.
`TRIALING`	The customer is in a free trial period. No payments are charged yet.
`ACTIVE`	The subscription is active and in good standing.
`PAST_DUE`	An invoice payment attempt failed. Renewals are retried.
`UNPAID`	Retries failed, and the subscription is unpaid (access should be restricted).
`CANCELED`	The subscription has been cancelled and is inactive.
`PAUSED`	Billing cycles are temporarily paused and can be resumed.

Create a Subscription

Subscribe a customer to a pricing plan.

POST /subscriptions

Request Parameters

Parameter	Type	Required	Description
`customerId`	`string`	Yes	ID of the Customer record.
`priceId`	`string`	Yes	ID of the price representing the plan.
`quantity`	`integer`	No	Quantity of seats/units (defaults to `1`).
`trialDays`	`integer`	No	Number of free trial days before billing starts.

Example Request

curl https://api.xtopay.co/subscriptions \
  -H "Authorization: Bearer YOUR_SESSION_OR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_cl8z2e9z...",
    "priceId": "price_cl8z2e8z...",
    "quantity": 1,
    "trialDays": 14
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "sub_cl9a1b2c3000...",
    "customerId": "cust_cl8z2e9z...",
    "status": "TRIALING",
    "currency": "GHS",
    "trialStart": "2026-06-05T12:00:00Z",
    "trialEnd": "2026-06-19T12:00:00Z",
    "currentPeriodStart": "2026-06-05T12:00:00Z",
    "currentPeriodEnd": "2026-06-19T12:00:00Z",
    "createdAt": "2026-06-05T12:00:00Z"
  }
}

Cancel a Subscription

Cancel a subscription immediately or schedule it to cancel at the end of the current billing period.

PATCH /subscriptions/:id/cancel

Request Parameters

Parameter	Type	Required	Description
`atPeriodEnd`	`boolean`	No	If `true`, waits until the end of the billing period to cancel. If `false`, cancels immediately.

Example Request

curl -X PATCH https://api.xtopay.co/subscriptions/sub_cl9a1b2c3000.../cancel \
  -H "Authorization: Bearer YOUR_SESSION_OR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "atPeriodEnd": true
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "sub_cl9a1b2c3000...",
    "status": "ACTIVE",
    "cancelAt": "2026-07-05T12:00:00Z",
    "canceledAt": "2026-06-05T12:45:00Z"
  }
}

Pause a Subscription

Pause recurring billing cycles. The subscription status transitions to PAUSED.

PATCH /subscriptions/:id/pause

Example Request

curl -X PATCH https://api.xtopay.co/subscriptions/sub_cl9a1b2c3000.../pause \
  -H "Authorization: Bearer YOUR_SESSION_OR_SECRET_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "sub_cl9a1b2c3000...",
    "status": "PAUSED"
  }
}

Resume a Subscription

Resume a paused subscription to reactive billing cycles.

PATCH /subscriptions/:id/resume

Example Request

curl -X PATCH https://api.xtopay.co/subscriptions/sub_cl9a1b2c3000.../resume \
  -H "Authorization: Bearer YOUR_SESSION_OR_SECRET_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "sub_cl9a1b2c3000...",
    "status": "ACTIVE"
  }
}

Subscriptions API

On this page