Catalog your goods and services, define complex billing plans, and set price points.

Products & Pricing

Products represent the goods, services, or software licenses you sell. Prices represent how much they cost, the currency they're priced in, and whether they recur on a subscription basis.

Create a Product

Define a new product item in your catalog.

POST /v1/products

Request Scopes

products:write

Request Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Human-readable name of the product (e.g. `"Enterprise Plan"`).
`description`	`string`	No	A description of what this product offers.
`type`	`string`	No	Type of product: `SERVICE`, `GOOD`, `DIGITAL`. Defaults to `SERVICE`.
`imageUrl`	`string`	No	An absolute URL to an image asset representing the product.
`metadata`	`object`	No	Flat key-value object containing product metadata.

Example Request

curl https://api.xtopay.co/v1/products \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cloud Hosting Standard",
    "description": "Virtual Private Server with 4GB RAM",
    "type": "SERVICE",
    "imageUrl": "https://example.com/assets/vps.png"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "prod_cl8z2j...",
    "name": "Cloud Hosting Standard",
    "description": "Virtual Private Server with 4GB RAM",
    "imageUrl": "https://example.com/assets/vps.png",
    "type": "SERVICE",
    "active": true,
    "createdAt": "2026-06-05T12:00:00Z",
    "updatedAt": "2026-06-05T12:00:00Z",
    "prices": []
  }
}

List Products

Retrieve products registered in your account.

GET /v1/products

Request Scopes

products:read

Query Parameters

Parameter	Type	Description
`active`	`string`	Set `true` to only return active products, or `false` to return archived ones.
`limit`	`integer`	Maximum results to return per page (range 1–100, default `20`).
`cursor`	`string`	Pagination cursor. Retrieve from the `nextCursor` value of a previous response.

Example Request

curl "https://api.xtopay.co/v1/products?active=true&limit=10" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Create a Price

Attach a price point to an existing product. Prices can be one-time charges or recurring subscriptions.

POST /v1/products/:id/prices

Request Scopes

products:write

Request Parameters

Parameter	Type	Required	Description
`unitAmount`	`integer`	Yes	The cost in minor units (must be a positive integer, e.g. `1000` is 10.00 GHS/USD).
`currency`	`string`	No	ISO 4217 currency code. Defaults to `"GHS"`.
`nickname`	`string`	No	Friendly name for this pricing (e.g. `"Monthly Billing"`).
`scheme`	`string`	No	Pricing scheme: `FLAT`, `PER_UNIT`, `TIERED`, `VOLUME`. Defaults to `FLAT`.
`isRecurring`	`boolean`	No	Set `true` to make this price recurring. Defaults to `false`.
`interval`	`string`	Yes (if recurring)	Subscription frequency: `DAY`, `WEEK`, `MONTH`, `YEAR`.
`intervalCount`	`integer`	No	Number of intervals between renewals (e.g. interval `MONTH` and count `3` is quarterly). Defaults to `1`.
`trialPeriodDays`	`integer`	No	Optional trial days for subscriptions built with this price.
`metadata`	`object`	No	Flat key-value object containing price metadata.

Example Request

curl https://api.xtopay.co/v1/products/prod_cl8z2j.../prices \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unitAmount": 45000,
    "currency": "GHS",
    "nickname": "Monthly Hosting Fee",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalCount": 1
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "price_cl8z2k...",
    "nickname": "Monthly Hosting Fee",
    "currency": "GHS",
    "unitAmount": 45000,
    "scheme": "FLAT",
    "isRecurring": true,
    "interval": "MONTH",
    "intervalCount": 1,
    "trialPeriodDays": null,
    "active": true,
    "createdAt": "2026-06-05T12:05:00Z"
  }
}

Archive a Price

Archiving a price deactivates it. Customers cannot subscribe to archived prices, but existing active subscriptions using it remain unaffected.

DELETE /v1/products/:id/prices/:priceId

Request Scopes

products:write

Example Request

curl -X DELETE https://api.xtopay.co/v1/products/prod_cl8z2j.../prices/price_cl8z2k... \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "price_cl8z2k...",
    "active": false
  }
}

Products & Pricing

On this page