> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Customers — GET /customers

> Retrieve a paginated, filterable list of the customers who have paid you. Filter by email, order count, total spent, and date. Requires customers:read.

Returns a paginated list of your customers, newest first. A customer is created automatically the first time an email pays you; `order_count` and `total_spent` stay in sync as payments settle. Requires the `customers:read` scope.

## Request

**`GET https://api.blockra.io/customers`**

### Query parameters

<ParamField query="page" default="1" type="integer">
  Page number (1-based).
</ParamField>

<ParamField query="limit" default="25" type="integer">
  Items per page (max 100).
</ParamField>

<ParamField query="sort" type="string">
  Sort column: `id`, `email`, `order_count`, `total_spent`, or `created_at`.
</ParamField>

<ParamField query="order" default="desc" type="string">
  `asc` or `desc`.
</ParamField>

<ParamField query="filter_id" type="string">
  Exact customer ID.
</ParamField>

<ParamField query="filter_email" type="string">
  Substring match on the customer email.
</ParamField>

<ParamField query="order_count_min" type="integer">
  Minimum number of settled payments.
</ParamField>

<ParamField query="order_count_max" type="integer">
  Maximum number of settled payments.
</ParamField>

<ParamField query="total_spent_min" type="number">
  Minimum lifetime spend (net fiat).
</ParamField>

<ParamField query="total_spent_max" type="number">
  Maximum lifetime spend (net fiat).
</ParamField>

<ParamField query="start_date" type="string">
  ISO date — created on or after.
</ParamField>

<ParamField query="end_date" type="string">
  ISO date — created before.
</ParamField>

## Response

<ResponseField name="items" type="array">
  The customers on this page.
</ResponseField>

<ResponseField name="total" type="integer">
  Total matching customers.
</ResponseField>

<ResponseField name="page" type="integer">
  Current page.
</ResponseField>

<ResponseField name="limit" type="integer">
  Page size.
</ResponseField>

<ResponseField name="total_pages" type="integer">
  Total number of pages.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.blockra.io/customers?limit=10&sort=total_spent&order=desc" \
    -H "X-API-Key: bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "items": [
        {
          "id": "cus_9z8y7x6w5v4u3t2s1r0q",
          "email": "buyer@example.com",
          "name": null,
          "order_count": 4,
          "total_spent": 312.40,
          "created_at": "2026-06-02T09:14:00.000Z"
        }
      ],
      "total": 1,
      "page": 1,
      "limit": 10,
      "total_pages": 1
    },
    "error": null
  }
  ```
</ResponseExample>