List Customers

Returns a paginated list of customers for your merchant account.

Endpoint

GET /v1/customers

Authentication

Requires API key authentication via X-API-Key header.

For JWT authentication, use GET /v1/customers/jwt instead.

Query Parameters

Parameter	Type	Description
limit	integer	Number of customers to return (default: 10, max: 100)
starting_after	string	Cursor for forward pagination. Returns customers created after this ID
ending_before	string	Cursor for backward pagination. Returns customers created before this ID
email	string	Filter by exact email match
search	string	Search by name or email (partial match)

Example Request

curl "https://api.example.com/v1/customers?limit=10" \
  -H "X-API-Key: sk_live_xxxxx"

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "cus_abc123def456",
      "object": "customer",
      "email": "[email protected]",
      "name": "John Doe",
      "phone": "[phone]",
      "address": {
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94102",
        "country": "US"
      },
      "companyName": "Acme Inc",
      "taxId": null,
      "description": null,
      "metadata": {},
      "created": 1706554800,
      "updated": 1706554800
    },
    {
      "id": "cus_xyz789ghi012",
      "object": "customer",
      "email": "[email protected]",
      "name": "Jane Smith",
      "phone": null,
      "address": null,
      "companyName": null,
      "taxId": null,
      "description": null,
      "metadata": null,
      "created": 1706554000,
      "updated": 1706554000
    }
  ],
  "hasMore": true
}

Pagination

Use cursor-based pagination to iterate through results:

# Get first page
curl "https://api.example.com/v1/customers?limit=10" \
  -H "X-API-Key: sk_live_xxxxx"

# Get next page using the last customer ID
curl "https://api.example.com/v1/customers?limit=10&starting_after=cus_xyz789ghi012" \
  -H "X-API-Key: sk_live_xxxxx"

Filtering by Email

curl "https://api.example.com/v1/[email protected]" \
  -H "X-API-Key: sk_live_xxxxx"

Searching

curl "https://api.example.com/v1/customers?search=john" \
  -H "X-API-Key: sk_live_xxxxx"

Errors

Code	Description
400	Invalid query parameters
401	Invalid or missing API key