Model pricing plans, manage customer subscriptions, billing cycles, trials, and renewals.

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 manage 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.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/subscriptions`
Request Type	`POST`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`payments:write`

Request Parameters

Parameter	Type	Required	Description
`customerId`	`String`	Yes	ID of the Customer record (e.g. `cust_cl8z2e9z...`).
`priceId`	`String`	Yes	ID of the price representing the plan (e.g. `price_cl8z2e8z...`).
`quantity`	`Integer`	No	Quantity of seats or units (defaults to `1`).
`trialDays`	`Integer`	No	Number of free trial days before billing cycles start.

Code Examples

curl https://api.xtopay.co/v1/subscriptions \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_cl8z2e9z50000a",
    "priceId": "price_cl8z2e8z80000b",
    "quantity": 1,
    "trialDays": 14
  }'

Sample Response

201 Created

{
  "success": true,
  "data": {
    "id": "sub_cl9a1b2c30000z",
    "customerId": "cust_cl8z2e9z50000a",
    "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.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/subscriptions/:id/cancel`
Request Type	`PATCH`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`payments:write`

Path Parameters

Parameter	Type	Required	Description
`:id`	`String`	Yes	Unique Subscription ID to cancel.

Request Parameters

Parameter	Type	Required	Description
`atPeriodEnd`	`Boolean`	No	If `true`, schedules cancellation for the end of the billing period. If `false`, cancels immediately. Defaults to `false`.

Code Examples

curl -X PATCH https://api.xtopay.co/v1/subscriptions/sub_cl9a1b2c30000z/cancel \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "atPeriodEnd": true
  }'

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "sub_cl9a1b2c30000z",
    "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.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/subscriptions/:id/pause`
Request Type	`PATCH`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`payments:write`

Path Parameters

Parameter	Type	Required	Description
`:id`	`String`	Yes	Unique Subscription ID to pause.

Code Examples

curl -X PATCH https://api.xtopay.co/v1/subscriptions/sub_cl9a1b2c30000z/pause \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "sub_cl9a1b2c30000z",
    "status": "PAUSED"
  }
}

Resume a Subscription

Resume billing cycles for a paused subscription. The status transitions back to ACTIVE.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/subscriptions/:id/resume`
Request Type	`PATCH`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`payments:write`

Path Parameters

Parameter	Type	Required	Description
`:id`	`String`	Yes	Unique Subscription ID to resume.

Code Examples

curl -X PATCH https://api.xtopay.co/v1/subscriptions/sub_cl9a1b2c30000z/resume \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "sub_cl9a1b2c30000z",
    "status": "ACTIVE"
  }
}

Subscriptions API

On this page