# Pagination

Source: https://developers.weerom.com/docs/pagination

> The list envelope, walking every page with a cursor, and syncing only what changed.

## The list envelope

Every list answers the same shape:

```json
{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "WzE3OTUyODcxMzA0MTIsIjBiNmYyYTRlLTVkMWMtNGY3YS05YTNlLTJjOGQxZTZmNGI5MCJd"
}
```

| Field | Meaning |
| --- | --- |
| `data` | The objects on this page. |
| `has_more` | `true` when another page follows. |
| `next_cursor` | Send it back as `cursor` to get the next page. `null` on the last page. |

## Parameters

| Parameter | Values | Default |
| --- | --- | --- |
| `limit` | 1 to 100 | 25 |
| `cursor` | The `next_cursor` of the page before | Leave out for the first page |
| `order` | `asc` for oldest first, `desc` for newest first | `desc` |

Each list sorts on one time and then on the id:

| List | Sorted by |
| --- | --- |
| `/customers` | `created_at` |
| `/bookings` | `starts_at` |
| `/payments` | `paid_at` |

`/services`, `/staff` and `/availability` always fit on one page. They answer the same envelope with `has_more: false` and take no `cursor`.

A cursor points at the last object of a page, not at a page number. Objects added or removed while you walk the list do not shift the pages. Send the cursor back as it came, with the same filters and the same `order`. A cursor the API did not give out answers 400 with `param: "cursor"`.

## Walk every page

Ask for 100 objects a page and follow `next_cursor` until `has_more` is `false`.

```js tab="JavaScript"
const BASE = "https://api.weerom.com/v1";

async function* everyCustomer() {
  let cursor = null;
  do {
    const url = new URL(`${BASE}/customers`);
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
    });
    if (!response.ok) throw new Error(`WeerOm answered ${response.status}`);

    const page = await response.json();
    yield* page.data;
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);
}

for await (const customer of everyCustomer()) {
  console.log(customer.name);
}
```

```php tab="PHP"
<?php
const BASE = 'https://api.weerom.com/v1';

function everyCustomer(): Generator {
  $cursor = null;
  do {
    $query = ['limit' => 100];
    if ($cursor !== null) {
      $query['cursor'] = $cursor;
    }
    $curl = curl_init(BASE . '/customers?' . http_build_query($query));
    curl_setopt_array($curl, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WEEROM_KEY')],
    ]);
    $body = curl_exec($curl);
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    if ($status !== 200) {
      throw new RuntimeException("WeerOm answered $status");
    }

    $page = json_decode($body, true);
    yield from $page['data'];
    $cursor = $page['has_more'] ? $page['next_cursor'] : null;
  } while ($cursor !== null);
}

foreach (everyCustomer() as $customer) {
  echo $customer['name'], PHP_EOL;
}
```

```python tab="Python"
import os
import requests

BASE = "https://api.weerom.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['WEEROM_KEY']}"}

def every_customer():
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        response = requests.get(f"{BASE}/customers", params=params, headers=HEADERS)
        response.raise_for_status()

        page = response.json()
        yield from page["data"]
        if not page["has_more"]:
            break
        cursor = page["next_cursor"]

for customer in every_customer():
    print(customer["name"])
```

A full walk of 10,000 customers is 100 requests. At 120 requests a minute for each key, it fits in one minute. If you walk more than one list at a time with the same key, read [Rate limits](https://developers.weerom.com/docs/rate-limits).

## Sync only what changed

`/customers` and `/bookings` take `updated_after`. It returns only objects that changed after that moment, so a sync job can ask for the changes since its last run instead of walking everything.

1. On the first run, walk the whole list.
2. Remember the highest `updated_at` you saw.
3. On the next run, walk the list with `updated_after` set to that value, and update your copy with each object.

```bash
curl "https://api.weerom.com/v1/bookings?updated_after=2026-11-21T18:52:10.412Z&limit=100" \
  -H "Authorization: Bearer $WEEROM_KEY"
```

`updated_after` is strict: an object changed at exactly that moment does not come back. Every date filter takes a date, a time and an offset, such as `2026-11-01T00:00:00Z` or `2026-11-01T01:00:00+01:00`. A date without a time answers 400.

`updated_after` only filters. The list keeps its own sort, by `created_at` for customers and by `starts_at` for bookings, so take the highest `updated_at` from all pages, not from the last one.

For payments, filter on `paid_after` instead. [Send payments to Billit](https://developers.weerom.com/docs/use-cases/billit) shows that loop.

To hear about bookings and payments within seconds, without a schedule, use [webhooks](https://developers.weerom.com/docs/webhooks). A sync with `updated_after` once a day next to them catches any message your server missed.
