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

application/json

application/json

application/json

application/json

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"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid value for parameter.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#parameter_invalid"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "No valid API key provided.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#authentication_required"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "permission_denied",
    "message": "The API key does not have permission to perform this action.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#permission_denied"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_invalid_state",
    "message": "A customer with this email already exists.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_invalid_state"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#internal_error"
  },
  "request_id": "req_abc123def456"
}

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`.