# Customers (/reference/customers)

## List customers

`GET /v1/customers`

### Parameters

- `limit` (query, optional, integer)
- `cursor` (query, optional, string) — Opaque cursor from the previous page's `next_cursor`.
- `reference_id` (query, optional, string)
- `status` (query, optional, string)

### Responses

- `200` — Customers.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `id` (required, string (uuid))
    - `reference_id` (optional, string | null) — Your own id for this user. Unique per project; re-posting it returns the existing customer.
    - `name` (optional, string | null) — Their name on your platform. Shown on your console's Customers and Addresses screens, and searchable there.
    - `email` (optional, string | null)
    - `status` (required, string, one of: active, disabled)
    - `metadata` (optional, object)
    - `created_at` (required, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Create a customer

`POST /v1/customers`

Idempotent on `reference_id`: re-posting an existing one returns 200 with the existing customer rather than creating a duplicate.

### Parameters

- `Idempotency-Key` (header, optional, string) — Recommended. Replays the stored response for a repeated key.

### Request body (required)

- `reference_id` (optional, string) — Your own user id.
- `name` (optional, string) — Their name on your platform — what your console shows and searches.
- `email` (optional, string (email))
- `metadata` (optional, object)

### Responses

- `200` — The customer already existed.
  - `object` (required, string)
  - `id` (required, string (uuid))
  - `reference_id` (optional, string | null) — Your own id for this user. Unique per project; re-posting it returns the existing customer.
  - `name` (optional, string | null) — Their name on your platform. Shown on your console's Customers and Addresses screens, and searchable there.
  - `email` (optional, string | null)
  - `status` (required, string, one of: active, disabled)
  - `metadata` (optional, object)
  - `created_at` (required, string (date-time))
- `201` — Created.
  - `object` (required, string)
  - `id` (required, string (uuid))
  - `reference_id` (optional, string | null) — Your own id for this user. Unique per project; re-posting it returns the existing customer.
  - `name` (optional, string | null) — Their name on your platform. Shown on your console's Customers and Addresses screens, and searchable there.
  - `email` (optional, string | null)
  - `status` (required, string, one of: active, disabled)
  - `metadata` (optional, object)
  - `created_at` (required, string (date-time))
- `400` — Validation failed.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## GET /v1/customers/{id}

`GET /v1/customers/{id}`

### Parameters

- `id` (path, required, string (uuid))

### Responses

- `200` — The customer.
  - `object` (required, string)
  - `id` (required, string (uuid))
  - `reference_id` (optional, string | null) — Your own id for this user. Unique per project; re-posting it returns the existing customer.
  - `name` (optional, string | null) — Their name on your platform. Shown on your console's Customers and Addresses screens, and searchable there.
  - `email` (optional, string | null)
  - `status` (required, string, one of: active, disabled)
  - `metadata` (optional, object)
  - `created_at` (required, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — Not found — also returned for another project's customer, so a 404 never confirms existence.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## PATCH /v1/customers/{id}

`PATCH /v1/customers/{id}`

### Parameters

- `id` (path, required, string (uuid))

### Request body (required)

- `name` (optional, string | null)
- `email` (optional, string | null (email))
- `status` (optional, string, one of: active, disabled)
- `metadata` (optional, object)

### Responses

- `200` — Updated.
  - `object` (required, string)
  - `id` (required, string (uuid))
  - `reference_id` (optional, string | null) — Your own id for this user. Unique per project; re-posting it returns the existing customer.
  - `name` (optional, string | null) — Their name on your platform. Shown on your console's Customers and Addresses screens, and searchable there.
  - `email` (optional, string | null)
  - `status` (required, string, one of: active, disabled)
  - `metadata` (optional, object)
  - `created_at` (required, string (date-time))
- `400` — No fields to update, or validation failed.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — Not found.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.