docs

Create a customer

Creates a new customer record. At least one contact method (email or phone) is required. Customers are environment-specific (test vs live database).

POST
/customers
  Creates a new customer record.
  
  At least one contact method (email or phone) is required.
  Customers are environment-specific (test vs live database).

Authorization

api-key
AuthorizationBearer <token>

API key for merchant integrations. Send as Authorization: Bearer <your key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/customers" \  -H "Content-Type: application/json" \  -d '{    "name": "John Doe",    "email": "john@example.com",    "phone": "+201234567890",    "currency": "EGP",    "address": {      "line1": "123 Main St",      "city": "Cairo",      "country": "EG"    },    "metadata": {      "source": "simulation"    }  }'
{
  "id": "cus_abc123",
  "merchantId": "merch_xyz789",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+201234567890",
  "currency": "EGP",
  "spendData": {
    "amountDisputeLosses": "0",
    "amountRefunded": "0",
    "averageOrderValue": "0",
    "currency": "EGP",
    "firstPurchaseAt": "",
    "grossSpend": "0",
    "lastPurchaseAt": "",
    "netSpend": "0",
    "numPayments": "0"
  },
  "balance": "0",
  "createdAt": "2024-01-01T00:00:00.000Z"
}
Empty
Empty

List customers GET

Lists customers with search and pagination. Returns only essential fields: id, createdAt, name, phone, email, and latestPaymentMethod. Search supports customer ID, name, email, or phone (supports comma-separated terms).

Get customer by ID GET

Retrieves customer lifecycle information (id, type, name, email, phone, address, metadata). Response shape is identical to the `customer.*` webhook payload. For transaction counts + payment methods, call `GET /customers/:id/stats`.