Catalog your goods and services, define pricing points, and configure recurring billing structures.

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.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/products`
Request Type	`POST`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`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.

Code Examples

curl https://api.xtopay.co/v1/products \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -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"
  }'

Sample Response

201 Created

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

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/products`
Request Type	`GET`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`products:read`

Query Parameters

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

Code Examples

curl "https://api.xtopay.co/v1/products?active=true&limit=1" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "prod_cl8z2lh820000d",
        "name": "Cloud Hosting Standard",
        "description": "Virtual Private Server with 4GB RAM",
        "active": true,
        "createdAt": "2026-06-05T12:00:00Z"
      }
    ],
    "nextCursor": "prod_cl8z2lh820000d",
    "hasMore": false
  }
}

Create a Price

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

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

Path Parameters

Parameter	Type	Required	Description
`:id`	`String`	Yes	Unique ID of the Product to attach the price to.

Request Parameters

Parameter	Type	Required	Description
`unitAmount`	`Integer`	Yes	The cost in minor units (must be a positive integer, e.g. `1000` = 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*	Subscription frequency: `DAY`, `WEEK`, `MONTH`, `YEAR`. *Mandatory if `isRecurring` is `true`.
`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.

Code Examples

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

Sample Response

201 Created

{
  "success": true,
  "data": {
    "id": "price_cl8z2lh820000e",
    "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 point deactivates it. Customers cannot subscribe to archived prices, but existing active subscriptions using it remain unaffected.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/products/:id/prices/:priceId`
Request Type	`DELETE`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`products:write`

Path Parameters

Parameter	Type	Required	Description
`:id`	`String`	Yes	Unique ID of the Product parent record.
`:priceId`	`String`	Yes	Unique ID of the Price record to deactivate.

Code Examples

curl -X DELETE https://api.xtopay.co/v1/products/prod_cl8z2lh820000d/prices/price_cl8z2lh820000e \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "price_cl8z2lh820000e",
    "active": false
  }
}

Products & Pricing

On this page