# List customers

Source: https://developers.weerom.com/docs/reference/customers/listCustomers

```http
GET https://api.weerom.com/v1/customers
```

Customers sorted by when the shop first saw them. Filter by `email` or `phone` to look one up, or by `updated_after` to fetch what changed since your last sync.

**Keys:** a key that may read. A public key gets 403.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no | `next_cursor` from the page before. Leave out for the first page. At most 200 characters. |
| `limit` | query | integer | no | How many objects a page holds. 1 to 100, default `25`. |
| `order` | query | `asc`, `desc` | no | The list sorts on `created_at`, then the id. `desc` puts the newest customer first. Default `desc`. |
| `email` | query | string | no | The exact address, in any case. At most 254 characters. |
| `phone` | query | string | no | The exact number in E.164, such as +32470123456. At most 20 characters. |
| `updated_after` | query | string (date-time) | no | Only customers changed after this moment. ISO 8601 with an offset, such as 2026-11-01T00:00:00Z. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].blocked` | boolean | The shop no longer takes online bookings from them. |
| `data[].created_at` | string (date-time) | When the shop first saw this customer. |
| `data[].email` | string or null | Null when the shop has no address for them. |
| `data[].has_account` | boolean | Whether they sign in on the shop's site. |
| `data[].id` | string (uuid) | The customer's id. |
| `data[].locale` | string | The language their mail goes out in. |
| `data[].name` | string | As the customer or staff typed it. |
| `data[].no_show_count` | integer | How many bookings staff marked as not shown up. |
| `data[].object` | `customer` |  |
| `data[].phone` | string | E.164. |
| `data[].postal_code` | string or null | Null when the customer never gave one. |
| `data[].updated_at` | string (date-time) | When the record last changed. |
| `has_more` | boolean | Whether another page follows this one. |
| `next_cursor` | string or null | Send as `cursor` for the next page. Null on the last. |
| `object` | `list` |  |

Example:

```json
{
  "data": [
    {
      "blocked": false,
      "created_at": "2026-04-11T09:05:22.000Z",
      "email": "lotte@example.com",
      "has_account": true,
      "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
      "locale": "nl",
      "name": "Lotte Peeters",
      "no_show_count": 0,
      "object": "customer",
      "phone": "+32470123456",
      "postal_code": "9000",
      "updated_at": "2026-11-18T14:02:11.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "object": "list"
}
```

### 400

A parameter or a field is missing or malformed.

### 401

No key, an unknown key or a revoked key.

### 403

The shop's plan does not include the API, or this kind of key may not call this.

### 429

Too many requests. Retry-After says when.

Every error answers `{ "error": { "code", "message", "param", "request_id" } }`. `param` is only on some 400 answers. See [Errors](https://developers.weerom.com/docs/errors).

## Keys

A read key or a write key. A public key answers 403 `key_not_allowed`.

## Sort

By `created_at`, the moment the shop first saw the customer, then by `id`. `order=desc`, the default, lists the newest first. `order=asc` starts with the oldest.

## Filters

- `email` matches the whole address in any case. `Lotte@Example.com` finds `lotte@example.com`. Part of an address finds nothing.
- `phone` matches the stored number exactly, as E.164: `+32470123456`. The API does not rewrite `0470 12 34 56` for you.
- `updated_after` leaves out a customer changed at that exact moment.

## What it does

- There is no endpoint that makes a customer. A booking makes its customer.

## When a field is null

- `email` is `null` when the shop has no email for the customer.
- `postal_code` is `null` when the customer never gave one.

## Errors

Besides 401 for a missing, unknown or removed key, 403 `plan_required`, 429 `rate_limited` and 500 `internal_error`, which every endpoint can answer:

| Status | `code` | When | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | A parameter is malformed or unknown, a date has no time and offset, or the cursor is not one the API gave out. | Fix the parameter `param` names. |
