Customers

The Customers API allows you to create, retrieve, update, list, and delete customer profiles associated with your merchant account.

Authentication

Requests require authentication using your API key in the `X-API-Key` header. See the Authentication guide.

The customer object

Represents a customer profile containing contact information and other details. See Data Models for the full structure.

Endpoints

Create a customer

Creates a new customer profile.

Endpoint: `POST /customers`

Request body parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes	Customer’s full name.
`email`	`string`	No	Customer’s email address.
`phone_number`	`string`	No	Customer’s phone number (preferably E.164 format).
`whatsapp_number`	`string`	No	Customer’s WhatsApp number (preferably E.164 format).
`country`	`string`	No	Customer’s country name or code.
`city`	`string`	No	Customer’s city.
`address`	`string`	No	Customer’s street address.
`postal_code`	`string`	No	Customer’s postal code.
`is_business`	`boolean`	No	Set `true` if the customer is a business (default: `false`).
`metadata`	`object`	No	Key-value pairs for storing additional information.

Example request:

Example request for POST /customers

{
  "name": "Amadou Ba",
  "email": "amadou.ba@example.com",
  "phone_number": "+221771234567",
  "country": "Senegal",
  "city": "Dakar",
  "is_business": false
}

Example response (201 Created):

Example response for POST /customers

{
  "data": {
    "customer_id": "b78de3c9-7f76-4f43-9c5d-19d9f5c7c985",
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "organization_id": "0979ec77-9fb1-4c9a-8c55-d7fb6c182c9c",
    "name": "Amadou Ba",
    "email": "amadou.ba@example.com",
    "phone_number": "+221771234567",
    "whatsapp_number": null,
    "country": "Senegal",
    "city": "Dakar",
    "address": null,
    "postal_code": null,
    "is_business": false,
    "metadata": null,
    "created_at": "2025-04-04T14:21:49.955Z",
    "updated_at": "2025-04-04T14:21:49.955Z"
  }
}

Get a customer

Retrieves the details of a specific customer by their ID.

Endpoint: `GET /customers/{id}`

Path parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the customer (`customer_id`).

Example response (200 OK):

(Response structure is the same as the Create a customer response)

Update a customer

Updates the details of a specific customer.

Endpoint: `PATCH /customers/{id}`

Path parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the customer (`customer_id`).

Request body parameters:

(Include only the fields you want to update. Parameters are the same as for `Create a customer`, none are required.)

Example request:

Example request for PATCH /customers/{id}

{
  "phone_number": "+221779876543",
  "address": "123 Main St"
}

List customers

Returns a list of customers associated with your merchant account. Supports pagination and filtering.

Endpoint: `GET /customers`

Query parameters:

Parameter	Type	Required	Description
`limit`	`number`	No	Maximum number of customers to return (default: 20).
`page`	`number`	No	Page number for pagination (default: 1).
`email`	`string`	No	Filter customers by exact email address.
`phone_number`	`string`	No	Filter customers by exact phone number.

Note: By default, this endpoint only returns customers who have completed or refunded transactions. To see all customers, including newly created ones without transactions, you might need specific permissions or a different filter (check API updates for this behavior).

Example response (200 OK):

{
  "data": [
    {
      "customer_id": "b78de3c9-7f76-4f43-9c5d-19d9f5c7c985",
      // ... other customer fields
    }
    // ... more customer objects
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20
    // Potentially other pagination fields like total_count, total_pages
  }
}

Delete a customer

Deletes a specific customer profile.

Endpoint: `DELETE /customers/{id}`

Path parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the customer (`customer_id`).

Example response (200 OK):

Example response for DELETE /customers/{id}

{
  "data": {
    "customer_id": "b78de3c9-7f76-4f43-9c5d-19d9f5c7c985",
    "deleted": true
  }
}

Error handling

Common errors include `400 Bad Request` for invalid input, `401 Unauthorized`, `404 Not Found` if the customer ID doesn’t exist, and `500 Internal Server Error`. Refer to the Errors guide for general structure and handling.

Merchants Products