Customers API

Customers represent the individuals or companies purchasing your products or subscribing to plans. Creating customer objects allows you to track transactions, invoice recurring fees, manage credit balances, and personalize checkout sessions.

Create a Customer

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

Request Parameters

Parameter	Type	Required	Description
`email`	`String`	Yes	Customer's email address. Must be unique per business.
`name`	`String`	Yes	Customer's full name.
`phone`	`String`	No	Customer's phone number in international format (e.g. `+233240000000`).
`externalId`	`String`	No	A unique identifier from your own system to map accounts.
`description`	`String`	No	Internal notes or description about the customer.
`currency`	`String`	No	Default currency code for invoicing (e.g., `"GHS"`).
`metadata`	`Object`	No	Flat key-value object containing customer metadata.

Code Examples

curl https://api.xtopay.co/v1/customers \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "yaw@example.com",
    "name": "Yaw Mensah",
    "phone": "+233249998888",
    "externalId": "user_db_yaw123",
    "description": "Enterprise API User",
    "currency": "GHS"
  }'

Sample Response

201 Created

{
  "success": true,
  "data": {
    "id": "cust_cl8z2lh820000a",
    "externalId": "user_db_yaw123",
    "email": "yaw@example.com",
    "name": "Yaw Mensah",
    "phone": "+233249998888",
    "description": "Enterprise API User",
    "metadata": null,
    "status": "ACTIVE",
    "currency": "GHS",
    "createdAt": "2026-06-05T12:00:00Z",
    "updatedAt": "2026-06-05T12:00:00Z"
  }
}

Retrieve a Customer

Get details for a customer profile by their unique Xtopay Customer ID.

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

Path Parameters

Parameter	Type	Required	Description
`:id`	`String`	Yes	Unique Customer ID (e.g. `cust_cl8z2lh820000a`).

Code Examples

curl https://api.xtopay.co/v1/customers/cust_cl8z2lh820000a \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "cust_cl8z2lh820000a",
    "externalId": "user_db_yaw123",
    "email": "yaw@example.com",
    "name": "Yaw Mensah",
    "phone": "+233249998888",
    "description": "Enterprise API User",
    "metadata": null,
    "status": "ACTIVE",
    "currency": "GHS",
    "createdAt": "2026-06-05T12:00:00Z",
    "updatedAt": "2026-06-05T12:00:00Z"
  }
}

List Customers

Retrieve customer accounts with optional filters and cursor-based pagination.

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

Query Parameters

Parameter	Type	Required	Description
`email`	`String`	No	Filter customers whose email contains this substring (case-insensitive).
`status`	`String`	No	Filter by customer status: `ACTIVE`, `INACTIVE`, `BLOCKED`.
`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/customers?email=yaw&limit=1" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "cust_cl8z2lh820000a",
        "email": "yaw@example.com",
        "name": "Yaw Mensah",
        "phone": "+233249998888",
        "status": "ACTIVE",
        "createdAt": "2026-06-05T12:00:00Z"
      }
    ],
    "nextCursor": "cust_cl8z2lh820000a",
    "hasMore": false
  }
}

Update a Customer

Modify specific fields on an existing customer record.

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

Path Parameters

Parameter	Type	Required	Description
`:id`	`String`	Yes	Unique Customer ID to update.

Request Parameters

Parameter	Type	Required	Description
`name`	`String`	No	Updated customer name.
`phone`	`String`	No	Updated phone number (pass `null` to clear).
`description`	`String`	No	Updated internal notes description (pass `null` to clear).
`status`	`String`	No	Set customer status: `ACTIVE`, `INACTIVE`, `BLOCKED`.
`metadata`	`Object`	No	Updated metadata payload. Overwrites current metadata.

Code Examples

curl -X PATCH https://api.xtopay.co/v1/customers/cust_cl8z2lh820000a \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Yaw Mensah Jr.",
    "status": "ACTIVE"
  }'

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "cust_cl8z2lh820000a",
    "externalId": "user_db_yaw123",
    "email": "yaw@example.com",
    "name": "Yaw Mensah Jr.",
    "phone": "+233249998888",
    "description": "Enterprise API User",
    "status": "ACTIVE",
    "createdAt": "2026-06-05T12:00:00Z",
    "updatedAt": "2026-06-06T15:00:00Z"
  }
}

Customers API

On this page