Create or Update a Customer

POST

/customers

Creates a new customer or updates an existing one (upsert). The customer is matched by phone_number within your merchant account.

Upsert behavior:

If no customer with the given phone_number exists, a new customer is created with status active and 0 points balance.

If a customer already exists with that phone_number, the provided fields are updated (only non-null fields are overwritten).

This endpoint requires an Idempotency-Key header to prevent duplicate customer creation from retried requests.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

Customer created or updated successfully.

Body

🟠400Bad Request

🟠401Unauthorized

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/customers' \
--header 'Idempotency-Key: customer-create-20260203-001' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "jane@example.com",
    "phone_number": "+2348012345678",
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1995-06-15T00:00:00.000Z"
}'

Response Example

200 - Example 1

{
    "status": true,
    "message": "Customer created successfully",
    "data": {
        "uid": "cust_abc123def456",
        "email": "jane@example.com",
        "phone_number": "+2348012345678",
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": "1995-06-15",
        "status": "active",
        "points_balance": 1500,
        "created_at": "2026-01-15T10:30:00.000Z"
    }
}

Modified at 2026-02-25 12:17:15

List Customers