# List bookings

Source: https://developers.weerom.com/docs/reference/bookings/listBookings

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

Appointments sorted by start time. Time staff blocked off for a break is not a booking and is left out.

**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 `starts_at`, then the id. `desc` puts the latest start first. Default `desc`. |
| `customer_id` | query | string (uuid) | no | Only this customer's. |
| `staff_id` | query | string (uuid) | no | Only this staff member's. |
| `starts_after` | query | string (date-time) | no | Only bookings that start at or after this moment. ISO 8601 with an offset, such as 2026-11-01T00:00:00Z. |
| `starts_before` | query | string (date-time) | no | Only bookings that start before this moment. ISO 8601 with an offset, such as 2026-11-01T00:00:00Z. |
| `status` | query | `confirmed`, `completed`, `cancelled`, `no_show` | no | Only bookings in this state. |
| `updated_after` | query | string (date-time) | no | Only bookings 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[].cancel_reason` | string | Empty unless cancelled. |
| `data[].cancelled_at` | string (date-time) or null | When it was cancelled. Null while it is not cancelled. |
| `data[].code` | string | The short code the customer sees. |
| `data[].comments` | string | What the customer wrote when booking. |
| `data[].created_at` | string (date-time) | When the booking was made. |
| `data[].currency` | string | ISO 4217 code of every amount on this object. |
| `data[].customer` | object | Who the booking is for, as written on the booking when it was made. |
| `data[].customer.email` | string or null |  |
| `data[].customer.id` | string (uuid) or null | Null when the customer record was erased. |
| `data[].customer.name` | string |  |
| `data[].customer.phone` | string or null |  |
| `data[].discount_percent` | integer | Percent off the list price. 0 without a deal. |
| `data[].ends_at` | string (date-time) | When the appointment ends. |
| `data[].id` | string (uuid) | The booking's id. |
| `data[].list_price_cents` | integer | The price before any deal. |
| `data[].locale` | string | The language the customer's mail about it goes out in. |
| `data[].minutes` | integer | How long the appointment takes. |
| `data[].object` | `booking` |  |
| `data[].payment` | object or null | Set once staff noted a payment. Null until then. |
| `data[].payment.amount_cents` | integer | What the customer paid for the service, VAT included. |
| `data[].payment.method` | string or null | How they paid. Null when staff did not say. |
| `data[].payment.paid_at` | string (date-time) | When staff noted the payment. |
| `data[].payment.tip_cents` | integer |  |
| `data[].price_cents` | integer | The price the customer was promised, VAT included. |
| `data[].service` | object |  |
| `data[].service.id` | string (uuid) or null | The service's id. Null when the shop deleted the service since. |
| `data[].service.name` | string | The service's name when the booking was made. |
| `data[].source` | `web`, `admin` | `web` for an online booking, `admin` for one staff typed in. |
| `data[].staff_id` | string (uuid) | Who the booking is with. |
| `data[].starts_at` | string (date-time) | When the appointment starts. |
| `data[].status` | `confirmed`, `completed`, `cancelled`, `no_show` | `confirmed` is booked and still to come or not yet closed by staff. `completed` is done. `no_show` means the customer did not come. |
| `data[].updated_at` | string (date-time) | When the booking 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": [
    {
      "cancel_reason": "",
      "cancelled_at": null,
      "code": "UEAMEFC9",
      "comments": "",
      "created_at": "2026-11-18T14:02:11.000Z",
      "currency": "EUR",
      "customer": {
        "email": "lotte@example.com",
        "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
        "name": "Lotte Peeters",
        "phone": "+32470123456"
      },
      "discount_percent": 0,
      "ends_at": "2026-11-21T10:15:00.000Z",
      "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
      "list_price_cents": 4000,
      "locale": "nl",
      "minutes": 45,
      "object": "booking",
      "payment": {
        "amount_cents": 4000,
        "method": "bancontact",
        "paid_at": "2026-11-21T10:12:40.000Z",
        "tip_cents": 200
      },
      "price_cents": 4000,
      "service": {
        "id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
        "name": "Knippen en baard"
      },
      "source": "web",
      "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
      "starts_at": "2026-11-21T09:30:00.000Z",
      "status": "completed",
      "updated_at": "2026-11-21T10:12:40.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 `starts_at`, then by `id`. `order=desc`, the default, puts the latest start first, so the furthest booking in the future comes first. `order=asc` starts with the earliest.

## Filters

- `starts_after` includes a booking that starts at that exact moment.
- `starts_before` leaves out a booking that starts at that exact moment. The two together cover a day without overlap: `starts_after=2026-11-21T00:00:00+01:00&starts_before=2026-11-22T00:00:00+01:00`.
- `updated_after` leaves out a booking changed at that exact moment.
- `status`, `staff_id` and `customer_id` match exactly. Filters combine with AND.

## What it does

- Time staff blocked off for a break is not a booking and never shows up.
- `updated_after` only filters. The list keeps its sort by `starts_at`, so a sync takes the highest `updated_at` from every page. See [Pagination](https://developers.weerom.com/docs/pagination#sync-only-what-changed).

## When a field is null

- `cancelled_at` is `null` until the booking is cancelled.
- `payment` is `null` until staff note a payment.
- `service.id` is `null` when the booking is not linked to a service record. The name written on the booking still shows.
- `customer.id` is `null` when the shop erased the customer's record. The booking keeps the name, email and phone written on it.
- `customer.email` is `null` when the booking holds no email. Staff may book without one.
- `customer.phone` is `null` when the booking holds no phone number.

## 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, an id is not a UUID, or the cursor is not one the API gave out. | Fix the parameter `param` names. |
