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

# Customers

> List and read customer records.

`https://exclusivo.one/api/v1` · scopes `customers:read`, `customers:write`

```http theme={"system"}
GET /api/v1/customers
```

| Parameter | Type    | Default |                                            |
| --------- | ------- | ------- | ------------------------------------------ |
| `limit`   | integer | `50`    | Max 100                                    |
| `cursor`  | string  | —       | A customer id from `pagination.nextCursor` |
| `segment` | string  | —       | Filter by segment                          |

```bash theme={"system"}
curl "https://exclusivo.one/api/v1/customers?limit=50" \
  -H "Authorization: Bearer ex_live_your_key_here"
```

```json theme={"system"}
{
  "data": [
    {
      "id": "cus_xyz789",
      "email": "buyer@example.com",
      "name": "A. Buyer",
      "ordersCount": 3,
      "totalSpent": "168.00",
      "subscribed": true,
      "createdAt": "2026-06-02T11:20:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null,
    "count": 12
  }
}
```

As with products and orders, `segment` filters the page you got — page until
`hasMore` is false rather than stopping on a short one.

## subscribed isn't implied by ordering

Someone who has bought from you isn't on your marketing list unless they opted
in.

<Warning>
  If you're exporting this to send mail from somewhere else, honour the same rules
  — and re-export. Unsubscribe status is authoritative at send time, and a list
  pulled today is stale tomorrow.
</Warning>

Unsubscribed records stay in the data as your suppression list.

## This is personal data

A key with `customers:read` reads your customers' details. Keep it server-side,
scope it narrowly, and replace it if it's ever been anywhere public.

→ [Authentication](/api/authentication)

## Errors

| Status |                        |
| ------ | ---------------------- |
| `401`  | Missing or invalid key |
| `403`  | Wrong scope            |
| `404`  | Not in your shop       |
| `429`  | Rate limited           |

## Related

* [Orders](/api/store/orders) — `userId` on an order is a customer id.
* [Webhooks](/api/webhooks) — `customer.created`, `customer.updated`.