# Authentication

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

> The three kinds of key, where a shop makes them, what 401 and 403 mean, and how to keep a key safe.

Every request carries a key in the `Authorization` header:

```http
GET /v1/payments HTTP/1.1
Host: api.weerom.com
Authorization: Bearer wo_live_1_3f9a1c2e5b7d4a68c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5
```

A key is a prefix, the shop's number, `_` and 48 hex characters. It belongs to one shop and works on that shop only.

## Three kinds of key

| Kind | Starts with | Where to use it | What it may do |
| --- | --- | --- | --- |
| Read | `wo_live_` | On a server | Read everything the API has: the shop, services, staff, free times, customers, bookings and payments. |
| Write | `wo_live_` | On a server | Read everything, and make, move and cancel bookings and change customers. |
| Public | `wo_pub_` | In a web page or an app, where anyone can read it | Read the shop, its services, its staff and its free times, and make a booking under a visitor's limits. It reads no customer and no booking. |

Pick the kind with the least it needs. An invoicing sync reads, so it gets a read key. A booking page in the browser gets a public key. A chat assistant that books from your server gets a write key.

A key of the wrong kind answers 403 `key_not_allowed`. A public key that asks for `/customers` gets it, and so does a read key that sends `POST /bookings`. The [API reference](https://developers.weerom.com/docs/reference) names the kinds each endpoint takes.

### Public keys

A public key opens what a visitor to the shop's own site already sees. A booking made with it is a visitor's booking:

- The shop's rules apply, as on its own booking form, and the key may not send `"as": "staff"`.
- The same limits as the shop's form apply: per address, per phone number, per email, and 4 open bookings from one address. Over them, the answer is 429 `limit_reached`.

All requests from a server come from one address, so a public key on a server would hit the limit per address quickly. A server uses a write key. [Build a booking page](https://developers.weerom.com/docs/booking-page) covers both.

## Make a key

1. Sign in to the shop's WeerOm admin as an administrator. Other roles cannot make or remove keys.
2. Open **Settings**, then **Features**, then **Connections**.
3. Under "What will use the key", give it a name that says where it goes, such as "Billit" or "Booking page".
4. Under "What it may do", pick **Read** for a read key, **Read and change** for a write key, or **Take bookings from a web page** for a public key.
5. Copy the key. The admin shows it once. WeerOm stores a hash of the key, not the key, so nobody can show it again later.

The shop must be on the Premium plan. A shop holds up to 10 working keys. Make one key for each tool, so you can remove one without breaking the others.

## Keep a key safe

A read or write key reads every customer's name, email and phone number. Treat it like a password.

- Keep it in an environment variable or your platform's secret store. Leave it out of source code and out of Git.
- Call the API from your server. A `wo_live_` key in a web page or a mobile app is a key anyone can read.
- If a key leaks, remove it and make a new one.

A public key may sit in a page. The worst a stranger can do with it is what they could do on the shop's own booking form.

## Remove a key

Remove a key in the same place you made it: **Settings**, **Features**, **Connections**. It stops working at once and every request with it answers 401 with the code `revoked_key`.

## When a key fails

| Status | `code` | What happened | What to do |
| --- | --- | --- | --- |
| 401 | `missing_key` | No `Authorization: Bearer` header. | Send the header, with `Bearer`, a space and the key. |
| 401 | `invalid_key` | WeerOm knows no such key. | Check that you copied the whole key. |
| 401 | `revoked_key` | Someone at the shop removed the key. | Ask the shop for a new one. |
| 403 | `plan_required` | The shop is not on the Premium plan. | Ask the shop to move to Premium. The same key works again from then on. |
| 403 | `key_not_allowed` | The key works, but its kind may not call this endpoint. | Use a key of the kind the endpoint takes. Ask the shop for one. |

A 401 answer also carries `WWW-Authenticate: Bearer realm="WeerOm API"`.

A shop that leaves Premium keeps its keys. They answer 403 until the shop is on Premium again, and then they work without a change on your side.

> **Stop on a 401.** Do not retry a request that failed with 401. The answer will not change, and an address that sends 60 requests without a working key within 10 minutes gets 429 before WeerOm looks at the key.


# Build a booking page

Source: https://developers.weerom.com/docs/booking-page

> Your own booking page on any site, with WeerOm as the backend. Pick a service, show free times, make the booking and handle every answer.

A shop that wants its own booking page, in its own design and on its own site, can keep WeerOm behind it. The page reads the services and the free times and sends the booking. WeerOm does the rest: it checks the shop's rules, puts the booking in the agenda, sends the customer the shop's confirmation mail and tells staff.

The page makes these calls, all with a public key:

| Step | Request |
| --- | --- |
| Read the shop's time zone | `GET /shop` |
| Pick a service | `GET /services` |
| Pick a staff member, if the shop lets customers choose | `GET /staff` |
| Show free times | `GET /availability` |
| Book | `POST /bookings` |

## Which key

| Where the code runs | Key | Why |
| --- | --- | --- |
| In the customer's browser | A public key, `wo_pub_...` | It reads only what the shop's own site shows, and it books under a visitor's limits. Anyone can read it in the page, and that is fine. |
| On your server, which calls WeerOm for the page | A write key, `wo_live_...` | Every request from a server comes from one address. A public key would hit the limit per address after 10 bookings in an hour. Keep this key out of the page. |

Both work with the code on this page. The examples use a public key in the browser, which needs no server at all. An administrator of the shop makes the key under **Settings**, **Features**, **Connections** and picks "Take bookings from a web page". See [Authentication](https://developers.weerom.com/docs/authentication).

## A helper for every call

Every request sends the key. Every error answers `{ "error": { "code", "message", "param", "request_id" } }`, and the page branches on `code`.

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

// A public key. It may sit in this file: it reads the shop, its services,
// its staff and its free times, and it makes bookings. Nothing else.
const KEY = "wo_pub_1_3f9a1c2e5b7d4a68c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5";

export class WeeromError extends Error {
  constructor(status, error, retryAfter) {
    super(error.message);
    this.status = status;
    this.code = error.code;
    this.param = error.param;
    this.requestId = error.request_id;
    this.retryAfter = retryAfter ? Number(retryAfter) : null;
  }
}

export async function weerom(path, { body, idempotencyKey } = {}) {
  const headers = { Authorization: `Bearer ${KEY}` };
  if (body) headers["Content-Type"] = "application/json";
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;

  const response = await fetch(`${BASE}${path}`, {
    body: body ? JSON.stringify(body) : undefined,
    headers,
    method: body ? "POST" : "GET",
  });
  const json = await response.json();
  if (!response.ok) {
    throw new WeeromError(response.status, json.error, response.headers.get("Retry-After"));
  }
  return json;
}
```

The API answers `Access-Control-Allow-Origin: *` and allows the `Authorization`, `Content-Type` and `Idempotency-Key` headers, so a page on any domain can call it.

### Read the shop

Every time in the API is UTC. Show times to the customer in the shop's own zone, which `GET /shop` names.

```js
const shop = await weerom("/shop");
// { "object": "shop", "name": "Studio Noord", "time_zone": "Europe/Brussels", "currency": "EUR", ... }

const clock = new Intl.DateTimeFormat("nl-BE", {
  hour: "2-digit",
  minute: "2-digit",
  timeZone: shop.time_zone,
});

// The shop's own date today, such as "2026-11-30".
const today = new Intl.DateTimeFormat("en-CA", { timeZone: shop.time_zone }).format(new Date());
```

### Pick a service

```js
const services = await weerom("/services?active=true");

for (const service of services.data) {
  const euros = (service.price_cents / 100).toFixed(0);
  console.log(`${service.name}, ${service.minutes} min, €${euros}`);
}
// Knippen en baard, 45 min, €40
```

`name` is in the shop's own language. `name_translations` holds `en`, `nl`, `fr`, `de` and `pt`. An empty string there means the shop did not translate it, so fall back to `name`.

`price_cents` is the list price with VAT. A deal or a loyalty card can lower it for one customer. The booking that comes back says what they will pay in `price_cents`.

### Pick a staff member, or let anyone do it

```js
const staff = await weerom("/staff?active=true");
const staffName = new Map(staff.data.map((person) => [person.id, person.name]));
```

The staff list does not say who does which service. The free times do: ask for them without `staff_id`, and every slot names the `staff_id` that would do it. Offer the staff who appear there.

### Show free times

```js
async function freeTimes(serviceId, date, staffId) {
  const query = new URLSearchParams({ days: "7", date, service_id: serviceId });
  if (staffId) query.set("staff_id", staffId);
  const slots = await weerom(`/availability?${query}`);
  return slots.data;
}

const slots = await freeTimes(serviceId, today);
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "slot",
      "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
      "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
      "starts_at": "2026-11-30T09:00:00.000Z",
      "ends_at": "2026-11-30T09:45:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

| Parameter | What it does |
| --- | --- |
| `service_id` | Required. The service to book. An inactive or unknown service answers 404. |
| `date` | Required. The first day, as a date in the shop's own calendar: `2026-11-30`. Not a time and not UTC. 30 November in Brussels is 30 November whatever zone the customer is in. |
| `days` | 1 to 14. How many days from `date` on. 1 when left out. |
| `staff_id` | Only this staff member's free times. Leave it out to get the free times of everyone active who does the service. |

The list is sorted by `starts_at`, then by `staff_id`. Without `staff_id`, two staff free at 10:00 give two slots at 10:00. For an "anyone" choice, show each time once and keep the first slot for it:

```js
function oncePerTime(slots) {
  const seen = new Map();
  for (const slot of slots) {
    if (!seen.has(slot.starts_at)) seen.set(slot.starts_at, slot);
  }
  return [...seen.values()];
}

for (const slot of oncePerTime(slots)) {
  console.log(clock.format(new Date(slot.starts_at)), staffName.get(slot.staff_id));
}
// 10:00 Sam
```

The free times follow the shop's rules and its agenda: opening hours, bookings already made, the lead time and how far ahead a customer may book. A day outside those comes back with no slots.

### Book

Send the slot's `service_id`, `staff_id` and `starts_at` as they came, with the customer's details.

```js
async function book(slot, person, idempotencyKey) {
  return weerom("/bookings", {
    body: {
      customer: { email: person.email, name: person.name, phone: person.phone },
      comments: person.comments,
      locale: "nl",
      service_id: slot.service_id,
      staff_id: slot.staff_id,
      starts_at: slot.starts_at,
    },
    idempotencyKey,
  });
}
```

| Field | Notes |
| --- | --- |
| `customer.name` | First and last name. A booking with one name answers 400 "First and last name are required". |
| `customer.phone` | With the country code, such as `+32470123456`. A number without one is read as a number in the shop's country. A customer the shop already knows by this phone is reused, else WeerOm makes one. |
| `customer.email` | Required for a booking made as a customer. The confirmation and the reminder go here. |
| `comments` | A note to the shop, up to 500 characters. |
| `locale` | The language of the customer's mail: `en`, `nl`, `fr`, `de` or `pt`. The shop's own when left out. |
| `remind_by_email` | `false` turns off the reminder mail. `true` when left out. |

A public key always books as a customer and may not send `as`. The answer is 201 with the booking:

```json
{
  "object": "booking",
  "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
  "code": "UEAMEFC9",
  "status": "confirmed",
  "starts_at": "2026-11-30T09:00:00.000Z",
  "ends_at": "2026-11-30T09:45:00.000Z",
  "price_cents": 4000,
  "currency": "EUR",
  "source": "web",
  "...": "..."
}
```

Show the `code` on the thank-you screen. Staff find the booking by it.

## Book once, even on a bad connection

A phone on a train sends the booking, the connection drops, and the page cannot know whether it went through. Send an `Idempotency-Key` and retry with the same one. If the first request made the booking, the retry gets that same booking back with the header `Idempotent-Replayed: true`, and no second booking is made.

Make one key when the customer presses Book, and a new one when they change the time or their details.

```js
async function bookOnce(slot, person) {
  const idempotencyKey = crypto.randomUUID();
  for (let attempt = 1; ; attempt++) {
    try {
      return await book(slot, person, idempotencyKey);
    } catch (error) {
      const network = error instanceof TypeError;
      const busy = error.code === "request_in_progress" || error.status >= 500;
      if (!(network || busy) || attempt === 3) throw error;
      await new Promise((done) => setTimeout(done, attempt * 2000));
    }
  }
}
```

[Safe retries](https://developers.weerom.com/docs/idempotency) has the rules.

## Handle the answer

```js
try {
  const booking = await bookOnce(slot, person);
  showThanks(booking.code);
} catch (error) {
  if (!(error instanceof WeeromError)) throw error;

  switch (error.code) {
    case "slot_taken":
      // Someone else booked this time a moment ago.
      showMessage("Someone booked this time a moment ago. Pick another one.");
      showSlots(await freeTimes(slot.service_id, today));
      break;
    case "invalid_request":
      // The shop's own sentence, such as "Email is required".
      showFieldError(error.param, error.message);
      break;
    case "limit_reached":
      showMessage("Too many bookings in a short time. Call the shop or try again later.");
      break;
    case "bookings_paused":
      showMessage("The shop takes no online bookings right now. Call the shop.");
      break;
    case "not_allowed":
      showMessage("The shop cannot take this booking online. Call the shop.");
      break;
    case "not_found":
      // The service or the staff member is no longer bookable.
      showServices(await weerom("/services?active=true"));
      break;
    default:
      showMessage(`Something went wrong. Quote ${error.requestId} to the shop.`);
  }
}
```

`showThanks`, `showMessage`, `showSlots`, `showFieldError` and `showServices` stand for your own page's code.

| Status | `code` | When | What the page does |
| --- | --- | --- | --- |
| 201 | | The booking is made. | Show the code and the time. |
| 400 | `invalid_request` | A field is missing or does not fit the shop's rules. `message` says which, in English: "First and last name are required", "Email is required", "That email does not look right". `param` names the field when the API knows it. | Show the message next to the field, or your own words for it. |
| 403 | `not_allowed` | The shop blocked this customer from booking online. | Ask them to call the shop. |
| 404 | `not_found` | The service or the staff member is gone or inactive. | Load the services again. |
| 409 | `slot_taken` | The time is no longer free. Someone was faster, or the shop changed its hours. | Ask for the free times again and let the customer pick another. |
| 429 | `limit_reached` | Too many bookings from this address or for this person, or the customer already holds as many open bookings as the shop allows. | Say so. Do not retry in a loop. `Retry-After` says how long when the limit is per address or per person. |
| 503 | `bookings_paused` | The shop paused online booking. | Show the shop's phone number. |

A visitor's limits are the same as on the shop's own booking form. Today they are 10 booking requests an hour from one address, 5 bookings an hour for one phone number, 3 for one email, and 4 open bookings from one address. Every key also has its 120 requests a minute. See [Rate limits](https://developers.weerom.com/docs/rate-limits).

## What the customer gets

The booking is the same as one made on the shop's own site:

- The shop's confirmation mail, in the shop's look and in `locale`, with a button to manage the booking. From there the customer can move or cancel it under the shop's rules. Your page needs no screen for that.
- The reminder mail before the appointment, unless you sent `remind_by_email: false`.
- Staff get their usual notice of a new booking, and the booking shows in the agenda.
- A deal or a loyalty card the customer has applies to the price, as on the shop's own site.

## From a server instead

The same calls work from your server with a write key. Two things change:

- The visitor's limits do not apply, so your server must stop abuse itself, for example with its own limit per address.
- A write key may send `"as": "staff"`. That books as the shop. It skips the lead time, the limit on how far ahead, the paused switch, the cap on open bookings and a block on the customer. It needs no email and no last name, and it applies no deal. Leave it out for a page customers use, so the shop's rules hold.

A write key reads every customer and every booking. Keep it on the server. [An assistant that books](https://developers.weerom.com/docs/use-cases/assistant) shows this setup.


# Changelog

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

> What changed in the WeerOm API, newest first.

## v1, webhooks

WeerOm posts a signed JSON message to the shop's addresses when a booking or a payment changes. Nothing in the API changed.

- Four events: `booking.created`, `booking.updated`, `booking.cancelled` and `payment.completed`.
- The shop adds up to 5 addresses in its admin, under Settings, Features, Connections, and picks the events for each.
- Each address has its own secret, `whsec_` and 64 hex characters. Every message carries `WeerOm-Signature: t=...,v1=...`, an HMAC-SHA256 of the time and the body.
- `data.object` is the booking or the payment as `GET /bookings/{id}` or `GET /payments/{id}` answers it.
- 7 attempts over about 33 hours. An address that fails for 3 days is switched off.
- A test message from the admin.

See [Webhooks](https://developers.weerom.com/docs/webhooks).

## v1, bookings and three kinds of key

The API takes bookings and changes them. Every field and code of the first release keeps its meaning.

- `GET /availability`: the free times for a service, for 1 to 14 days, for one staff member or everyone who does the service.
- `POST /bookings`: books a free time through the shop's booking engine. The shop's rules apply, and the customer gets the shop's confirmation mail.
- `POST /bookings/{id}/cancel` and `POST /bookings/{id}/reschedule`.
- `PATCH /customers/{id}`: changes a customer's name or blocks them.
- `as` in the body of a write: `customer` keeps the shop's rules, `staff` acts as the shop.
- Three kinds of key: read, write and public. A public key starts with `wo_pub_` and may sit in a web page. Only an administrator of the shop makes keys.
- `Idempotency-Key` on every `POST` and `PATCH`, kept for 24 hours, with `Idempotent-Replayed: true` on a replayed answer.
- New error codes: `key_not_allowed`, `slot_taken`, `too_late`, `wrong_state`, `not_allowed`, `limit_reached`, `bookings_paused`, `idempotency_mismatch` and `request_in_progress`.
- A key holds the shop's number: `wo_live_1_3f9a...`.
- Examples on every object in [openapi.json](https://developers.weerom.com/openapi.json), so the reference shows a whole answer.

## v1, first release

The first version of the API. It read a shop's data and changed nothing.

- `GET /shop`: the shop the key belongs to.
- `GET /services` and `GET /services/{id}`, with the name in five languages.
- `GET /staff` and `GET /staff/{id}`.
- `GET /customers` and `GET /customers/{id}`. Filters: `email`, `phone`, `updated_after`.
- `GET /bookings` and `GET /bookings/{id}`. Filters: `status`, `staff_id`, `customer_id`, `starts_after`, `starts_before`, `updated_after`.
- `GET /payments` and `GET /payments/{id}`. Filters: `paid_after`, `paid_before`, `method`.
- Keys made by the shop under Settings, Features, Connections, on the Premium plan. Up to 10 for each shop.
- Cursor pagination, up to 100 objects a page.
- 120 requests a minute for each key, with `RateLimit-*` headers.
- One error shape, and `X-Request-Id` on every answer.
- An OpenAPI 3.1 file at [/openapi.json](https://developers.weerom.com/openapi.json).

Within v1, fields are added but never renamed or removed, and an error code never changes its meaning.

## What is coming

These are planned. None of them works today.

- Adding and removing webhook addresses through the API.
- Webhook events for customers.
- Test keys with their own data.
- Expanding a related object inside another, such as the whole customer inside a booking.
- Changing a booking's service.
- Noting a payment.


# Errors

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

> The shape of every error, what each code means and what to do about it.

## The shape

Every error answers JSON with one `error` object:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be a whole number from 1 to 100.",
    "param": "limit",
    "request_id": "req_3f9a1c2e5b7d4a68"
  }
}
```

| Field | Meaning |
| --- | --- |
| `code` | A fixed word. Branch on this. A code keeps its meaning for all of v1. |
| `message` | One English sentence for a person. The wording may change, so do not parse it. |
| `param` | The query parameter or body field at fault. Only on some 400 answers. |
| `request_id` | The id of this request. Quote it when you ask WeerOm about it. |

When the shop's booking engine refuses a write, `message` carries the engine's own sentence when it has one, such as "First and last name are required" or "Email is required". A booking page may show it to the customer.

## Codes

### Keys and requests

| Status | `code` | What happened | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | A parameter or body field is malformed, missing, out of range or unknown to the endpoint, or the booking does not fit the shop's rules. `param` names the field when there is one. | Fix the request. Sending it again unchanged gives the same answer. |
| 401 | `missing_key` | No key in `Authorization: Bearer`. | Send the key. |
| 401 | `invalid_key` | WeerOm knows no such key. | Check the key. |
| 401 | `revoked_key` | The shop removed this key. | Ask the shop for a new key. |
| 403 | `plan_required` | The shop is not on the Premium plan. | Ask the shop to move to Premium. The key works again from then on. |
| 403 | `key_not_allowed` | This kind of key may not call this endpoint. A public key reading customers, or a read key making a booking. | Use a key of the right kind. See [Authentication](https://developers.weerom.com/docs/authentication#three-kinds-of-key). |
| 404 | `not_found` | No object with this id, or no such endpoint. On a write, the service or the staff member is gone or inactive. | Check the id and the path. A payment's id is its booking's id, and an unpaid booking has no payment. |
| 429 | `rate_limited` | Too many requests. | Wait the seconds in `Retry-After`, then send it again. See [Rate limits](https://developers.weerom.com/docs/rate-limits). |
| 500 | `internal_error` | Something broke on WeerOm's side. | Retry after a few seconds. If it keeps happening, send WeerOm the `request_id`. |

### Bookings and customers

| Status | `code` | What happened | What to do |
| --- | --- | --- | --- |
| 403 | `not_allowed` | The shop does not allow this, for example a booking for a customer the shop blocked. | Do not retry. Send the customer to the shop. |
| 409 | `slot_taken` | The time is no longer free. Someone else booked it, or the shop changed its hours. | Ask `GET /availability` again and pick another time. |
| 409 | `too_late` | It is past the shop's cut-off for cancelling or moving online. | Tell the customer to call the shop. A write key may send `"as": "staff"` to act as the shop. |
| 409 | `wrong_state` | The booking is no longer open: it is cancelled, done or marked as a no-show. | Read the booking again with `GET /bookings/{id}` and show its `status`. |
| 429 | `limit_reached` | Too many bookings from one address or for one person in a short time, or the customer holds as many open bookings as the shop allows. | Do not retry in a loop. Wait the seconds in `Retry-After` when the answer has it, or tell the customer to call the shop. |
| 503 | `bookings_paused` | The shop paused online booking. | Try again later, or show the shop's phone number. A write key with `"as": "staff"` still books. |

### Retries

| Status | `code` | What happened | What to do |
| --- | --- | --- | --- |
| 409 | `idempotency_mismatch` | This `Idempotency-Key` was used for a different request. | Make a new key for a new request. |
| 409 | `request_in_progress` | The first request with this `Idempotency-Key` still runs. | Wait a second and send the same request again. |

[Safe retries](https://developers.weerom.com/docs/idempotency) explains both.

A parameter or body field the endpoint does not have answers 400 too. `GET /payments?paid_afer=...` fails with `param: "paid_afer"` instead of quietly returning every payment.

## What to retry

| Answer | Retry |
| --- | --- |
| 400, 401, 403, 404 | No. The answer will not change until the request or the shop changes. |
| 409 `slot_taken` | Not the same request. Ask for the free times again and book another one. |
| 409 `too_late`, `wrong_state`, `idempotency_mismatch` | No. |
| 409 `request_in_progress` | Yes, with the same `Idempotency-Key`, after a second. |
| 429 | After `Retry-After` seconds. For `limit_reached` without that header, not in a loop. |
| 500 | Yes, a few times, with a growing wait: 2, 4, then 8 seconds. Send an `Idempotency-Key` with every `POST` and `PATCH`, so a retry cannot do it twice. |
| 503 `bookings_paused` | Not until the shop opens online booking again. |

## Request ids

Every answer carries an `X-Request-Id` header, errors and successes alike. On an error, `request_id` in the body holds the same value.

```http
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_3f9a1c2e5b7d4a68
Cache-Control: no-store
```

Log it beside every failed request. With the id, WeerOm can find the request in its logs.


# Safe retries

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

> Send an Idempotency-Key with a POST or a PATCH, and a retry after a timeout changes nothing twice.

A request to make a booking times out. Did WeerOm make it? Your code cannot tell. Send it again without protection and the customer may have two bookings.

`Idempotency-Key` solves this. Send any unique text in that header with a `POST` or a `PATCH`. WeerOm runs the first request and keeps its answer for 24 hours. A retry with the same key and the same request gets that answer back, and nothing runs a second time.

```bash
curl https://api.weerom.com/v1/bookings \
  -H "Authorization: Bearer $WEEROM_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b8e-9d4a-4f3e-8b7c-2a1d0e9f8c7b" \
  -d '{
    "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
    "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
    "starts_at": "2026-11-30T09:00:00.000Z",
    "customer": { "name": "Lotte Peeters", "phone": "+32470123456", "email": "lotte@example.com" }
  }'
```

## The rules

| You send | WeerOm answers |
| --- | --- |
| A new key | Runs the request and keeps the answer. |
| The same key and the same request, after the first one finished | The first answer, with its status, and the header `Idempotent-Replayed: true`. Nothing runs. |
| The same key while the first request still runs | 409 `request_in_progress`. Wait a second and send it again. |
| The same key with another method, path or body | 409 `idempotency_mismatch`. Use a new key for a new request. |
| The same key after the first request failed | Runs the request. A request that answered an error keeps nothing, so you may fix it and send it again under the same key. |

- The key is any text up to 255 characters. A UUID from `crypto.randomUUID()` is a good choice.
- Keys belong to one API key. Two tools with their own API keys cannot collide.
- WeerOm keeps a key for 24 hours. After that the same key runs the request again.
- `GET` ignores the header. Reading twice changes nothing.
- If the first request died on WeerOm's side without an answer, a retry a minute later runs it again.

The endpoints that take it: `POST /bookings`, `POST /bookings/{id}/cancel`, `POST /bookings/{id}/reschedule` and `PATCH /customers/{id}`.

## One key for each thing you mean to do

Make the key when you decide to do something, store it with that intent, and reuse it for every retry of it. A booking form makes one when the customer presses Book. A sync job can build it from its own data, such as `cancel-0b6f2a4e-...` for the cancellation of one booking, so a job that restarts sends the same key again.

Make a new key when the request changes: another time, another customer, another body.

## Retry with the same key

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

async function post(path, body, idempotencyKey) {
  for (let attempt = 1; ; attempt++) {
    let response;
    try {
      response = await fetch(`${BASE}${path}`, {
        body: JSON.stringify(body),
        headers: {
          Authorization: `Bearer ${process.env.WEEROM_KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey,
        },
        method: "POST",
      });
    } catch (networkError) {
      if (attempt === 4) throw networkError;
      await wait(attempt);
      continue;
    }

    const json = await response.json();
    if (response.ok) return json;

    const { code } = json.error;
    const again = code === "request_in_progress" || response.status >= 500;
    if (!again || attempt === 4) {
      throw new Error(`${response.status} ${code}: ${json.error.message}`);
    }
    await wait(attempt);
  }
}

const wait = (attempt) => new Promise((done) => setTimeout(done, 2 ** attempt * 1000));

const booking = await post("/bookings", bookingBody, crypto.randomUUID());
```

The waits grow: 2, 4, then 8 seconds. The sketch retries a lost connection, a 500 and `request_in_progress`. Other 4xx answers are about the request itself, such as `slot_taken` or `invalid_request`, so it stops and reports them. A 429 waits the seconds in `Retry-After` first: see [Rate limits](https://developers.weerom.com/docs/rate-limits).


# Introduction

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

> What the WeerOm API reads and changes, the webhooks it sends, where it lives and the rules every endpoint follows.

The WeerOm API lets your software work with a shop's data. It reads the shop, its services, its staff, its free times, its customers, its bookings and its payments. It also takes bookings, cancels and moves them, and changes customers, through the shop's own booking engine. The shop's rules apply and the shop's mail goes out, as if the customer had booked on the shop's own site. When a booking or a payment changes, WeerOm can post it to your server as a webhook.

## One address for every shop

```txt
https://api.weerom.com/v1
```

Every shop uses this base URL. The key you send says which shop you work with, and a key works on that shop and no other.

## What you can read

| Endpoint | What it returns |
| --- | --- |
| `GET /shop` | The shop the key belongs to: name, country, currency, time zone, language. |
| `GET /services` | Every service, with its price and its name in five languages. |
| `GET /staff` | Everyone customers can book with. Name and whether they are active. |
| `GET /availability` | The free times for one service, for 1 to 14 days, for one staff member or everyone who does the service. |
| `GET /customers` | Customers, newest first. Look one up by `email` or `phone`. |
| `GET /bookings` | Appointments, by start time. Filter by status, staff, customer and dates. |
| `GET /payments` | Bookings a customer paid for, by the moment staff noted the payment. |

Each list except `/availability` also has a `GET /{list}/{id}` for one object.

## What you can change

| Endpoint | What it does |
| --- | --- |
| `POST /bookings` | Books a free time. The customer gets the shop's confirmation mail. |
| `POST /bookings/{id}/cancel` | Cancels a booking and frees its time. |
| `POST /bookings/{id}/reschedule` | Moves a booking to another time or another staff member. |
| `PATCH /customers/{id}` | Changes a customer's name, or blocks them from booking online. |

There is no endpoint that makes a customer. A booking makes its customer, or reuses the one the shop knows by that phone number. The [API reference](https://developers.weerom.com/docs/reference) has every field.

## What WeerOm sends you

| Event | When |
| --- | --- |
| `booking.created` | A booking is made, online, by staff or through the API. |
| `booking.updated` | A booking moves, changes service, or is marked completed or a no-show. |
| `booking.cancelled` | A booking is cancelled. |
| `payment.completed` | Staff note a payment, or correct one. |

The shop adds your address in its admin and gives you a secret. Each message is signed with it. [Webhooks](https://developers.weerom.com/docs/webhooks) covers the message, the signature and the retries.

## Rules every endpoint follows

- **Keys.** Send `Authorization: Bearer ...` with every request. A read key reads, a write key also changes, and a public key sits in a web page and books. See [Authentication](https://developers.weerom.com/docs/authentication).
- **Who acts.** A write takes `as`: `customer`, the default, keeps the shop's rules, and `staff` acts as the shop. A public key may not send it.
- **Retries.** A `POST` or `PATCH` takes an `Idempotency-Key`, so a retry after a timeout does nothing twice. See [Safe retries](https://developers.weerom.com/docs/idempotency).
- **Lists.** A list answers `{ "object": "list", "data", "has_more", "next_cursor" }`. See [Pagination](https://developers.weerom.com/docs/pagination).
- **Money.** Amounts are whole cents with VAT included, beside a `currency`. `4000` with `"EUR"` is €40.
- **Time.** Times are ISO 8601 in UTC, such as `2026-11-21T18:15:00.000Z`. The shop's own zone is `time_zone` on `GET /shop`.
- **Names.** Field names are snake_case. A field, once out, keeps its name and its meaning for all of v1.
- **Errors.** Every error answers `{ "error": { "code", "message", "request_id" } }`. See [Errors](https://developers.weerom.com/docs/errors).
- **Limits.** 120 requests a minute for each key. See [Rate limits](https://developers.weerom.com/docs/rate-limits).
- **Browsers.** The API answers `Access-Control-Allow-Origin: *`, so a page on any site can call it. Only a public key belongs in a page. A read or write key in a browser is a key anyone can read.
- **Changes.** A webhook tells your server within seconds that a booking or a payment changed. Where nobody can add an address, or a run once an hour is enough, ask for what changed with `updated_after` or `paid_after`. See [Webhooks](https://developers.weerom.com/docs/webhooks#polling-as-the-fallback).

## Who can use it

A shop on the Premium plan makes keys in its WeerOm admin. If you build for a shop, ask the owner for a key of the kind you need. If you run the shop, the [quickstart](https://developers.weerom.com/docs/quickstart) starts with making one.

## What people build

[Build a booking page](https://developers.weerom.com/docs/booking-page) is the full guide for a booking page of your own. The [use cases](https://developers.weerom.com/docs/use-cases) cover ten more, from invoices in Billit to an assistant that books.

## The spec and files for AI tools

The reference on this site is built from the OpenAPI 3.1 file of the API. Feed the same file to a client generator or to Postman: [openapi.json](https://developers.weerom.com/openapi.json).

For an AI assistant or a coding agent:

- [llms.txt](https://developers.weerom.com/llms.txt) lists every page with one line on each, in the [llmstxt.org](https://llmstxt.org) format.
- [llms-full.txt](https://developers.weerom.com/llms-full.txt) holds every guide, use case and reference page as Markdown in one file, with the fields and examples of each endpoint.
- Every page is also Markdown at its own address with `.md` added, such as [/docs/webhooks.md](https://developers.weerom.com/docs/webhooks.md). The **Copy Markdown** button at the top of a page copies it.


# 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.


# Quickstart

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

> Make a key, send your first request and read the answer.

## Make a key

An administrator of the shop opens the WeerOm admin and goes to **Settings**, **Features**, **Connections**. The shop must be on the Premium plan.

They give the key a name, such as "Billit", and pick what it may do:

| Pick | Kind | Starts with | For |
| --- | --- | --- | --- |
| Read | Read key | `wo_live_` | A server that reads, such as an invoicing sync. |
| Read and change | Write key | `wo_live_` | A server that also books, cancels and moves. |
| Take bookings from a web page | Public key | `wo_pub_` | A booking page in the browser. |

This quickstart reads payments, so it needs a read key. The admin shows the key once. Copy it then.

## Ask who the key belongs to

`GET /shop` is a good first call. It proves the key works and tells you the currency and time zone of everything else.

```bash tab="cURL"
curl https://api.weerom.com/v1/shop \
  -H "Authorization: Bearer $WEEROM_KEY"
```

```js tab="JavaScript"
const response = await fetch("https://api.weerom.com/v1/shop", {
  headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
});
console.log(await response.json());
```

```php tab="PHP"
<?php
$curl = curl_init('https://api.weerom.com/v1/shop');
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WEEROM_KEY')],
]);
print_r(json_decode(curl_exec($curl), true));
```

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

response = requests.get(
    "https://api.weerom.com/v1/shop",
    headers={"Authorization": f"Bearer {os.environ['WEEROM_KEY']}"},
)
print(response.json())
```

The answer:

```json
{
  "object": "shop",
  "name": "Studio Noord",
  "country": "BE",
  "currency": "EUR",
  "time_zone": "Europe/Brussels",
  "locale": "nl",
  "url": "https://studionoord.weerom.be"
}
```

## Read a list

Ask for the most recent payment:

```bash
curl "https://api.weerom.com/v1/payments?limit=1" \
  -H "Authorization: Bearer $WEEROM_KEY"
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "payment",
      "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
      "booking_id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
      "booking_code": "UEAMEFC9",
      "paid_at": "2026-11-21T10:12:40.000Z",
      "starts_at": "2026-11-21T09:30:00.000Z",
      "description": "Knippen en baard",
      "amount_cents": 4000,
      "list_price_cents": 4000,
      "discount_percent": 0,
      "net_cents": 3306,
      "vat_cents": 694,
      "vat_percent": 21,
      "tip_cents": 200,
      "currency": "EUR",
      "method": "bancontact",
      "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
      "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
      "customer": {
        "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
        "name": "Lotte Peeters",
        "email": "lotte@example.com",
        "phone": "+32470123456"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "WzE3OTUyODcxMzA0MTIsIjBiNmYyYTRlLTVkMWMtNGY3YS05YTNlLTJjOGQxZTZmNGI5MCJd"
}
```

## Read the answer

- `amount_cents` is what the customer paid for the service, VAT included. `4000` is €40.
- `net_cents` and `vat_cents` split that amount. They always add up to `amount_cents`.
- `tip_cents` sits apart and is not part of `amount_cents`.
- `paid_at` is when staff noted the payment, in UTC. 10:12 UTC is 11:12 in Brussels in November.
- `has_more` is `true`, so another page follows. Send `next_cursor` back as `cursor` to get it. [Pagination](https://developers.weerom.com/docs/pagination) has a loop.

## Next

- [Authentication](https://developers.weerom.com/docs/authentication) covers the three kinds of key, keeping a key safe and what a 401 means.
- [Build a booking page](https://developers.weerom.com/docs/booking-page) shows free times and makes bookings with a public key.
- [Send payments to Billit](https://developers.weerom.com/docs/use-cases/billit) walks through an invoicing sync from start to end. The [use cases](https://developers.weerom.com/docs/use-cases) list nine more.
- [Webhooks](https://developers.weerom.com/docs/webhooks) tells your server about new bookings, changes and payments within seconds.
- The [API reference](https://developers.weerom.com/docs/reference) lists every endpoint, with a playground that takes your key.


# Rate limits

Source: https://developers.weerom.com/docs/rate-limits

> 120 requests a minute for each key, the headers that count them and how to back off.

## The numbers

| Who | Limit | Over the limit |
| --- | --- | --- |
| Each key | 120 requests a minute by default | 429 `rate_limited` until the minute is over |
| Each address without a working key | 60 requests in 10 minutes | 429 `rate_limited` before WeerOm looks at the key |

The count is per key, not per shop. Two tools with their own keys each get 120 requests a minute. Reads and writes count the same.

A page holds up to 100 objects, so one key reads up to 12,000 objects a minute.

## Bookings with a public key

A booking made with a public key is a visitor's booking, and it runs under the same limits as the shop's own booking form. Today they are:

| What counts | Limit |
| --- | --- |
| Booking requests from one address | 10 an hour |
| Bookings for one phone number | 5 an hour |
| Bookings for one email | 3 an hour |
| Open bookings made from one address | 4 |

Over one of them, `POST /bookings` answers 429 `limit_reached` with a `Retry-After` header. Every booking made as a customer, whatever the key, also counts against the shop's own cap on open bookings for one customer, when the shop set one. That answer is 429 `limit_reached` without `Retry-After`.

A write key books from a server, where every request comes from one address. It runs under its 120 requests a minute and not under these limits.

## The headers

Every answer that passed the key check carries three headers:

| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | Requests this key may make in a minute. `120`. |
| `RateLimit-Remaining` | Requests left in this minute. |
| `RateLimit-Reset` | Seconds until the count starts again. |

```http
HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 87
RateLimit-Reset: 41
```

Over the limit, the answer is 429 with a `Retry-After` header in seconds:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 23
```

```json
{
  "error": {
    "code": "rate_limited",
    "message": "This key may make 120 requests a minute. Try again in 23 seconds.",
    "request_id": "req_9c0d1e2f3a4b5c6d"
  }
}
```

## Back off

On a 429, wait the seconds in `Retry-After` and send the same request again. Requests sent in the meantime answer 429 as well.

```js tab="JavaScript"
async function weerom(path) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch(`https://api.weerom.com/v1${path}`, {
      headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
    });
    if (response.status !== 429) return response;

    const seconds = Number(response.headers.get("Retry-After") ?? "60");
    await new Promise((done) => setTimeout(done, seconds * 1000));
  }
  throw new Error("Still rate limited after 5 tries");
}
```

```php tab="PHP"
<?php
function weerom(string $path): array {
  for ($attempt = 0; $attempt < 5; $attempt++) {
    $wait = 60;
    $curl = curl_init('https://api.weerom.com/v1' . $path);
    curl_setopt_array($curl, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WEEROM_KEY')],
      CURLOPT_HEADERFUNCTION => function ($curl, $line) use (&$wait) {
        if (stripos($line, 'Retry-After:') === 0) {
          $wait = (int) trim(substr($line, 12));
        }
        return strlen($line);
      },
    ]);
    $body = curl_exec($curl);
    if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) !== 429) {
      return json_decode($body, true);
    }
    sleep($wait);
  }
  throw new RuntimeException('Still rate limited after 5 tries');
}
```

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

def weerom(path):
    for attempt in range(5):
        response = requests.get(
            f"https://api.weerom.com/v1{path}",
            headers={"Authorization": f"Bearer {os.environ['WEEROM_KEY']}"},
        )
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "60")))
    raise RuntimeError("Still rate limited after 5 tries")
```

## Stay under the limit

- Ask for `limit=100`. One request for 100 objects costs the same as one for 25.
- Sync with `updated_after` or `paid_after` instead of walking a whole list each time. See [Pagination](https://developers.weerom.com/docs/pagination#sync-only-what-changed).
- Watch `RateLimit-Remaining`. When it reaches 0, wait `RateLimit-Reset` seconds before the next request.
- Run one sync at a time for each key.
- Let [webhooks](https://developers.weerom.com/docs/webhooks) tell you about bookings and payments instead of asking every minute. A message from WeerOm costs no request.
- Poll on a schedule that fits. A job that asks every 5 minutes for what changed costs a few requests each time, far under 120 a minute.


# Overview

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

> Every endpoint, built from the API's OpenAPI file. Paste your key into any page to send a real request.

Every endpoint answers JSON and works on one shop: the shop the key belongs to. The base URL is `https://api.weerom.com/v1`.

## Endpoints

- Shop: [GET /shop](https://developers.weerom.com/docs/reference/shop/getShop.md) Get the shop
- Services: [GET /services](https://developers.weerom.com/docs/reference/services/listServices.md) List services; [GET /services/{id}](https://developers.weerom.com/docs/reference/services/getService.md) Get a service
- Staff: [GET /staff](https://developers.weerom.com/docs/reference/staff/listStaff.md) List staff; [GET /staff/{id}](https://developers.weerom.com/docs/reference/staff/getStaffMember.md) Get a staff member
- Availability: [GET /availability](https://developers.weerom.com/docs/reference/availability/listAvailability.md) List free times
- Customers: [GET /customers](https://developers.weerom.com/docs/reference/customers/listCustomers.md) List customers; [GET /customers/{id}](https://developers.weerom.com/docs/reference/customers/getCustomer.md) Get a customer; [PATCH /customers/{id}](https://developers.weerom.com/docs/reference/customers/updateCustomer.md) Change a customer
- Bookings: [GET /bookings](https://developers.weerom.com/docs/reference/bookings/listBookings.md) List bookings; [POST /bookings](https://developers.weerom.com/docs/reference/bookings/createBooking.md) Make a booking; [GET /bookings/{id}](https://developers.weerom.com/docs/reference/bookings/getBooking.md) Get a booking; [POST /bookings/{id}/cancel](https://developers.weerom.com/docs/reference/bookings/cancelBooking.md) Cancel a booking; [POST /bookings/{id}/reschedule](https://developers.weerom.com/docs/reference/bookings/rescheduleBooking.md) Move a booking
- Payments: [GET /payments](https://developers.weerom.com/docs/reference/payments/listPayments.md) List payments; [GET /payments/{id}](https://developers.weerom.com/docs/reference/payments/getPayment.md) Get a payment

## Try a request

Each endpoint page has a playground. Open it, paste your key into the `Authorization` field and press Send. Your browser calls `https://api.weerom.com/v1` itself. The key stays in this browser tab and never goes to this site's server.


# Bookkeeping with Accountable

Source: https://developers.weerom.com/docs/use-cases/accountable

> Build the same income lines the admin exports for Accountable, one per day and payment method, from the payments list.

**For** a Belgian shop owner who keeps their books in [Accountable](https://www.accountable.eu/en-be/), and the developer or accountant who wants the shop's income there each month without anyone pressing a button.

The shop's admin already exports a file for Accountable: under **Insights**, **Profit**, **Download CSV**. It holds the shop's expenses and one income line per day and payment method, never one per customer, at the shop's VAT rate. This script builds the same income lines from `GET /payments` on a schedule, so the file can land in the accountant's inbox on the first of each month.

| What | You need |
| --- | --- |
| Key | **Read key** A read key, on a server or your own computer. |
| Endpoints | `GET /shop` for the time zone, `GET /payments` for the month. |
| Accountable | An account. The script writes a file. It does not talk to Accountable. |

## Getting the lines into Accountable

We found no public API for Accountable. Its site lists no developer documentation, and its integrations page answered 404 when we looked on 2026-11-21. If Accountable publishes one later, a call to it can take the place of the file. Until then, this page does not guess at one.

So the script writes a CSV in the admin's layout, and a person takes it from there:

- Open it in Excel or Numbers and copy the lines into Accountable. This is the route the admin's own export is made for.
- Or mail it to the accountant.

Accountable's help centre describes [importing documents](https://www.accountable.eu/en-be/help-center/changing-accounting-software/) by dropping files on its web version. We could not confirm that it reads income lines from a CSV. Ask Accountable's support before you build on that.

## The lines

One line for each day and payment method:

| Column | Value |
| --- | --- |
| `date` | The day staff noted the payments, in the shop's time zone: `2026-11-21`. |
| `type` | `income` |
| `category` | `Appointments` |
| `description` | `Appointments, 1 visit` or `Appointments, 6 visits` |
| `supplier_or_customer` | Empty. A day's line has no single customer. |
| `amount_incl_vat` | The sum of `amount_cents` that day for that method, in euros: `240.00`. |
| `vat_percent` | `vat_percent` of the payments: `21`, or `0` for a shop under the exemption. |
| `vat` | The VAT inside the line's total. |
| `amount_excl_vat` | The line's total less the VAT. |
| `payment_method` | `method`: `cash`, `bancontact`, `credit_card`, `bancontact_pay` and so on. `not_noted` when staff did not say. |

The admin writes `category` and `description` in the shop's language. The script below writes them in English. Change the two words if the accountant reads Dutch or French.

Tips are left out, as in the admin's file. A tip belongs to the barber, and `tip_cents` is not part of `amount_cents`. Add a second line per day for tips if the shop's accountant asks for one.

### VAT once per line, not per payment

Every payment carries its own `net_cents` and `vat_cents`, each rounded half up. Add those up for a day and the VAT can be a cent off the admin's file, because the admin rounds once on the line's total. To match it to the cent, sum `amount_cents` and work out the VAT on the total with the same rule:

```txt
net = amount × 10,000 ÷ (10,000 + rate × 100), rounded half up to the cent
vat = amount − net
```

A day of six €40 cuts at 21% is €240.00, net €198.35, VAT €41.65. Six payments of €33.06 net would add up to €198.36.

## The script

Node 22. Run it with the month to export:

```bash
WEEROM_KEY=wo_live_... node accountable-export.js 2026-11
```

```js title="accountable-export.js"
import { writeFile } from "node:fs/promises";

const BASE = "https://api.weerom.com/v1";
const month = process.argv[2]; // "2026-11"

async function weerom(path) {
  const response = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
  });
  const json = await response.json();
  if (!response.ok) {
    throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
  }
  return json;
}

const addDays = (day, days) => {
  const date = new Date(`${day}T00:00:00Z`);
  date.setUTCDate(date.getUTCDate() + days);
  return date.toISOString().slice(0, 10);
};

// The net of a VAT-included amount, rounded half up, as WeerOm's admin does it.
function netOf(grossCents, vatPercent) {
  const divisor = BigInt(10_000 + Math.round(vatPercent * 100));
  return Number((2n * BigInt(grossCents) * 10_000n + divisor) / (2n * divisor));
}

const euros = (cents) => (cents / 100).toFixed(2);
const cell = (value) => (/[",\n]/.test(value) ? `"${value.replaceAll('"', '""')}"` : value);

const shop = await weerom("/shop");
const dayIn = new Intl.DateTimeFormat("en-CA", { timeZone: shop.time_zone });

const first = `${month}-01`;
const next = addDays(`${month}-28`, 7).slice(0, 7);
const last = addDays(`${next}-01`, -1);

// Ask a day wider on both sides, then keep what falls inside the month on
// the shop's own clock. That covers any time zone without offset maths.
const lines = new Map();
let cursor = null;
do {
  const query = new URLSearchParams({
    limit: "100",
    order: "asc",
    paid_after: `${addDays(first, -1)}T00:00:00Z`,
    paid_before: `${addDays(last, 2)}T00:00:00Z`,
  });
  if (cursor) query.set("cursor", cursor);
  const page = await weerom(`/payments?${query}`);

  for (const payment of page.data) {
    const day = dayIn.format(new Date(payment.paid_at));
    if (day < first || day > last) continue;

    const method = payment.method ?? "not_noted";
    const key = `${day} ${method}`;
    const line = lines.get(key) ?? { amount: 0, day, method, rate: payment.vat_percent, visits: 0 };
    line.amount += payment.amount_cents;
    line.visits += 1;
    lines.set(key, line);
  }
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

const head = [
  "date", "type", "category", "description", "supplier_or_customer",
  "amount_incl_vat", "vat_percent", "vat", "amount_excl_vat", "payment_method",
];

const rows = [...lines.values()]
  .sort((a, b) => a.day.localeCompare(b.day) || a.method.localeCompare(b.method))
  .map((line) => {
    const net = netOf(line.amount, line.rate);
    const visits = line.visits === 1 ? "1 visit" : `${line.visits} visits`;
    return [
      line.day, "income", "Appointments", `Appointments, ${visits}`, "",
      euros(line.amount), String(line.rate), euros(line.amount - net), euros(net), line.method,
    ];
  });

// The BOM lets Excel open the euro sign and accents as they are.
const csv = `﻿${[head, ...rows].map((row) => row.map(cell).join(",")).join("\n")}`;
await writeFile(`accountable-${month}.csv`, csv);
console.log(`${rows.length} lines for ${month}`);
```

The file opens in Excel and Numbers. Run it on the 1st of each month for the month before, with cron or a scheduled job, and mail it on:

```txt
0 7 1 * * WEEROM_KEY=wo_live_... node accountable-export.js $(date -v-1m +\%Y-\%m)
```

`date -v-1m` is the macOS form. On Linux it is `date -d "last month" +\%Y-\%m`.

A month of a busy shop is a few hundred payments: 3 to 5 requests, once a month.

## A running ledger with payment.completed

The monthly script reads payments weeks after they were noted, at the shop's VAT rate of that day. A webhook keeps each payment as it was when staff noted it.

1. The shop adds your address for **Payment noted**. See [Webhooks](https://developers.weerom.com/docs/webhooks#add-an-address).
2. For each `payment.completed` message, verify the signature and store `data.object` by its `id`. A payment staff correct arrives again with the same `data.object.id`. Replace the row you have, so the ledger holds the newest version.
3. On the 1st, build the lines from your own rows instead of `GET /payments`. Group and round them as above.

```js title="ledger-webhook.js"
// Called from your webhook server once verify() passed. See the Webhooks guide.
export async function onPaymentMessage(message) {
  if (message.type !== "payment.completed") return;
  const payment = message.data.object;
  const stored = await ledger.get(payment.id);
  // A retry of an older version can arrive after a newer one.
  if (stored && stored.paid_at >= payment.paid_at) return;
  await ledger.put(payment.id, payment);
}
```

`ledger` stands for your own table or file. Run the monthly script against the API once in a while as well, and compare the totals: a payment staff remove sends no message, and the ledger would still count it.

## Limits

- **The day of the payment, not of the cut.** The admin's file dates a line by the day of the appointment. The API gives `paid_at` and `starts_at` on every payment, and this script dates by `paid_at`, which a cash book wants. Staff note a payment at the chair, so the two are the same day unless a payment was noted later. Group by `starts_at` instead to follow the admin to the letter.
- **Unpaid cuts are missing.** The admin's file has a `not_noted` line for finished cuts nobody noted a payment for. `GET /payments` only lists bookings with a payment, so this script never has them. The `not_noted` lines it writes are payments staff noted without a method.
- **No expenses.** The admin's file also holds the shop's expenses. The API does not expose them. Take those from the admin's own export, or let Accountable read the receipts.
- **Today's VAT rate.** `vat_percent` is the shop's rate as it is set today, for old payments too. Export each month soon after it ends, or keep the [running ledger](#a-running-ledger-with-paymentcompleted).
- **Nothing goes to Accountable by itself.** Without a public Accountable API, a person copies or imports the lines.


# An assistant that books

Source: https://developers.weerom.com/docs/use-cases/assistant

> A chat or phone assistant that looks up free times and makes the booking, from your server with a write key.

**For** a shop that wants a chatbot on its site or in WhatsApp, or a voice assistant on its phone line, that answers "can I come in Saturday morning?" with a real time and books it.

The assistant runs on your server. When the customer asks for a time, it calls `GET /availability` and offers what is free. When the customer says yes and gives their name, phone and email, it calls `POST /bookings`. WeerOm books under the shop's rules and sends the customer the shop's confirmation mail, with the link to move or cancel.

| What | You need |
| --- | --- |
| Key | **Write key** A write key, on the server, never in the chat window. |
| Endpoints | `GET /shop`, `GET /services`, `GET /staff`, `GET /availability`, `POST /bookings`. With a lookup of the customer: `GET /customers` and `GET /bookings`, which `POST /bookings/{id}/cancel` and `/reschedule` can act on. |
| Assistant | Your chat or voice model, with tools it may call. Your own code connects them to the functions below. |

## Why a write key and not a public key

A public key books under a visitor's limits, counted per address. Every request from your server comes from the server's address, so a public key would stop after 10 booking requests in an hour for all your customers together. A write key runs under its own 120 requests a minute. Keep it on the server: it also reads every customer.

Leave `as` out, or send `"as": "customer"`. The assistant books as a customer, so the shop's lead time, its paused switch, its cap on open bookings and its blocked customers all apply, as on its own booking form. `"as": "staff"` would skip them. An assistant that strangers talk to should not.

## The tools

Give the assistant two tools: one that finds free times and one that books. Each is a small function on your server.

```js title="tools.js"
const BASE = "https://api.weerom.com/v1";

async function weerom(path, { body, idempotencyKey } = {}) {
  const headers = { Authorization: `Bearer ${process.env.WEEROM_KEY}` };
  if (body) headers["Content-Type"] = "application/json";
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
  const response = await fetch(`${BASE}${path}`, {
    body: body ? JSON.stringify(body) : undefined,
    headers,
    method: body ? "POST" : "GET",
  });
  const json = await response.json();
  return { ok: response.ok, json };
}

const shop = (await weerom("/shop")).json;
const services = (await weerom("/services?active=true")).json.data;
const staff = (await weerom("/staff?active=true")).json.data;
const clock = new Intl.DateTimeFormat("nl-BE", {
  dateStyle: "full",
  timeStyle: "short",
  timeZone: shop.time_zone,
});

/** Tool: free times for a service on a day, as text the model can read. */
export async function findFreeTimes({ serviceName, date, staffName }) {
  const service = services.find((s) => s.name.toLowerCase() === serviceName.toLowerCase());
  if (!service) return { error: `No service called ${serviceName}. Offer: ${services.map((s) => s.name).join(", ")}.` };
  const person = staffName ? staff.find((p) => p.name === staffName) : null;

  const query = new URLSearchParams({ date, days: "1", service_id: service.id });
  if (person) query.set("staff_id", person.id);
  const { ok, json } = await weerom(`/availability?${query}`);
  if (!ok) return { error: json.error.message };

  return {
    slots: json.data.map((slot) => ({
      label: `${clock.format(new Date(slot.starts_at))} with ${staff.find((p) => p.id === slot.staff_id)?.name}`,
      service_id: slot.service_id,
      staff_id: slot.staff_id,
      starts_at: slot.starts_at,
    })),
  };
}

/** Tool: book one slot from findFreeTimes for the person the assistant talks to. */
export async function bookSlot({ slot, name, phone, email, conversationId }) {
  const { ok, json } = await weerom("/bookings", {
    body: {
      customer: { email, name, phone },
      service_id: slot.service_id,
      staff_id: slot.staff_id,
      starts_at: slot.starts_at,
    },
    // One booking per conversation and time, however often the model retries.
    idempotencyKey: `${conversationId}-${slot.starts_at}-${slot.staff_id}`,
  });
  if (ok) return { booked: true, code: json.code, starts_at: json.starts_at };
  return { booked: false, code: json.error.code, message: json.error.message };
}
```

`date` is a day in the shop's own calendar, such as `2026-11-30`. Tell the model today's date on the shop's clock, so "Saturday" becomes the right day.

## What the assistant says back

| `bookSlot` returns | The assistant |
| --- | --- |
| `booked: true` | Gives the time and the `code`, and says a confirmation mail is on its way. |
| `slot_taken` | Says someone booked the time a moment ago and calls `findFreeTimes` again. |
| `invalid_request` | Asks for what `message` names. "First and last name are required" means it needs a last name. "Email is required" means it needs an email. |
| `limit_reached` | The customer holds as many open bookings as the shop allows. Offers to pass them to the shop. |
| `not_allowed` | The shop blocked this customer from booking online. Passes them to the shop without saying why. |
| `bookings_paused` | The shop takes no online bookings right now. Gives the shop's phone number. |

## How often

A conversation makes a few requests: one or two `GET /availability` calls and one `POST /bookings`. The services, staff and shop are read once at start. One key serves about 40 conversations a minute at 3 requests each before it reaches 120. No polling: the assistant asks when the customer asks.

## Limits

- **Who is on the other end.** The API trusts the name, phone and email the assistant sends. Anyone can give someone else's number. The shop's confirmation mail goes to the email given, so a wrong email means a confirmation nobody reads.
- **Moving and cancelling.** A write key can cancel and move with `POST /bookings/{id}/cancel` and `/reschedule`. To find the booking, look the customer up with `GET /customers?phone=...` and read `GET /bookings?customer_id=...&status=confirmed`. Proving the person on the line is that customer is yours to build. Until then, point them to the manage link in their confirmation mail.
- **The staff list does not say who does which service.** `GET /availability` without `staff_id` only returns staff who do it, so offer names from the slots.
- **Prices for one person.** `price_cents` on a service is the list price. A deal or a loyalty card can lower it. The booking that comes back has the price the customer will pay.


# Automations

Source: https://developers.weerom.com/docs/use-cases/automations

> n8n, Make or Zapier, started by a WeerOm webhook or on a schedule, with an HTTP request to WeerOm and your own steps after it.

**For** a shop or an agency that wires tools together without a server of its own: a message in the staff chat for every new booking, a row in a sheet for every cancellation, a block for a customer who missed two appointments.

The flow starts when WeerOm sends a webhook, a few seconds after a booking or a payment changes. Where the shop cannot add an address, it starts on a schedule and asks WeerOm what changed since the last run. The steps after it are the tool's own: post a message, add a row, send a mail. A flow that changes something in WeerOm sends a request with a write key.

| What | You need |
| --- | --- |
| Key | **Read key** A read key for a flow that only reads. **Write key** A write key for a flow that cancels, moves or blocks. |
| Webhook | An address from the tool's webhook trigger, which the shop adds in its admin. See [Webhooks](https://developers.weerom.com/docs/webhooks#add-an-address). |
| Endpoints | `GET /bookings/{id}` and `GET /payments/{id}` after a webhook. `GET /bookings`, `GET /customers` or `GET /payments` with a time filter on a schedule. `PATCH /customers/{id}` and the booking writes for a flow that changes things. |
| Tool | n8n, Make, Zapier or anything with a webhook trigger or a schedule, and an HTTP request step. |

What we checked in each tool's documentation on 2026-11-21 and 2026-11-22:

- **n8n** has a [Webhook](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/) node with a **Raw Body** option, and a [Crypto](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.crypto/) node with an **Hmac** action. It also has a [Schedule Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.scheduletrigger/) node and an [HTTP Request](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/) node that sends headers.
- **Make** has a [Webhooks app](https://apps.make.com/gateway) with a **Custom webhook** trigger. Its advanced settings can pass the request headers on. Make also has an [HTTP app](https://apps.make.com/http) with a "Make a request" module. We did not check how Make schedules a scenario.
- **Zapier** has [Webhooks by Zapier](https://help.zapier.com/hc/en-us/articles/8496288690317) with a **Catch Raw Hook** trigger, which passes the body unparsed with its headers, up to 2MB. [Schedule by Zapier](https://help.zapier.com/hc/en-us/articles/8496288648461) starts a Zap on an interval. We did not check which Zapier step sends a GET request with your own header.

## Start a flow from a webhook

1. Add the tool's webhook trigger. It gives you an HTTPS address.
2. The shop pastes that address under **Settings**, **Features**, **Connections**, **Updates for other software**, and switches on the events the flow needs.
3. The shop presses **Send a test**. The tool receives a message of type `test`, which you can use to map the fields.
4. Let the trigger answer at once. In n8n, set **Respond** to **Immediately**. WeerOm waits 10 seconds for a 2xx and then counts the attempt as failed.

The message is `{ "id", "type", "created_at", "data": { "object" } }`. `data.object` is the whole booking or payment. [Webhooks](https://developers.weerom.com/docs/webhooks#the-message) shows both.

### Trust the message, or read it again

Anyone who learns the address can post to it. The signature in `WeerOm-Signature` proves WeerOm sent the message. Checking it needs the raw body and an HMAC with the shop's secret, which most flow tools make hard.

The safe pattern for a flow tool: treat the message as a tip. Take `data.object.id` and read the object again with `GET /bookings/{id}` or `GET /payments/{id}` and a read key. Act on what the API answers. A forged message then costs one request and changes nothing, because an unknown id answers 404.

In n8n, you can check the signature itself instead. Turn on **Raw Body** in the Webhook node, split the header into `t` and `v1`, and compute an **Hmac** with SHA256 in a Crypto node over `t`, a dot and the raw body, with the shop's secret. Compare the result with `v1`, and refuse a `t` more than 300 seconds old. We did not build this flow end to end. [Verify the signature](https://developers.weerom.com/docs/webhooks#verify-the-signature) has the rules and a test value.

### Skip a message you have seen

A message can arrive twice. Keep the `id` of each message the flow handled, in a sheet or the tool's data store, and stop when it is there already.

## Start a flow on a schedule

### The request

Every tool asks for the same things. Fill them in like this:

| Setting | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://api.weerom.com/v1/bookings` |
| Header | `Authorization` with the value `Bearer wo_live_...`. Put the key in the tool's credentials store if it has one, not in the step's text. |
| Query | `updated_after` set to the run's start time less 16 minutes, as ISO 8601: `2026-11-21T09:44:00Z`. `limit` set to `100`. `order` set to `asc`. |

The answer is a list. Its `data` holds the bookings, and the next step loops over them.

```bash
curl "https://api.weerom.com/v1/bookings?updated_after=2026-11-21T09:44:00Z&limit=100&order=asc" \
  -H "Authorization: Bearer $WEEROM_KEY"
```

### Why 16 minutes for a 15-minute schedule

A tool's schedule drifts by a few seconds. A window one minute longer than the schedule overlaps the run before it, so no change falls between two runs. The cost is that a change near the edge can come twice. Make the step after it safe to repeat: update a row by the booking's `id` instead of adding one, or remember which `id` and `updated_at` you already posted.

A tool that stores state between runs can remember the highest `updated_at` it saw and send that instead. [Pagination](https://developers.weerom.com/docs/pagination#sync-only-what-changed) has that loop.

If `has_more` is `true`, more than 100 bookings changed in 15 minutes. That is rare for one shop. Ask again with `cursor` set to `next_cursor`, or run the flow more often.

## Flows to start from

| When | Webhook | Or on a schedule, ask for | Then |
| --- | --- | --- | --- |
| A new booking | `booking.created` | `GET /bookings?updated_after=...` and keep those with `created_at` inside the window | Post the time, `service.name` and `customer.name` to the staff chat. |
| A cancellation | `booking.cancelled` | `GET /bookings?updated_after=...&status=cancelled` | Add a row with `cancel_reason` to a sheet. |
| A payment | `payment.completed` | `GET /payments?paid_after=...` | Post the day's total to the owner. |
| A second no-show | `booking.updated` with `status` `no_show`, then `GET /customers/{id}` for `customer.id` | `GET /customers?updated_after=...` | Keep customers with `no_show_count` of 2 or more and `blocked: false`, and block them with a write key, below. |

## Changing something in WeerOm

A step that changes something sends a write key and an `Idempotency-Key`. Build the idempotency key from the object, so a flow that runs twice does it once:

| Setting | Value |
| --- | --- |
| Method | `PATCH` |
| URL | `https://api.weerom.com/v1/customers/{id}`, with the customer's `id` from the step before |
| Headers | `Authorization: Bearer wo_live_...`, `Content-Type: application/json`, `Idempotency-Key: block-{id}` |
| Body | `{ "blocked": true }` |

A blocked customer can no longer book online. Bookings they already have stay. The same pattern works for `POST /bookings/{id}/cancel` with `{ "reason": "..." }`.

## How often

A webhook flow runs once per change, a few seconds after it. Reading the object again is one request per run.

A scheduled flow every 15 minutes is 4 requests an hour, against 120 a minute for the key. Five flows on one key stay far under the limit. Pick the schedule when the shop cannot add an address, or when a flow needs a total over time rather than each change.

## Limits

- **No webhook for customers.** A change to a customer sends nothing. A flow about customers runs on a schedule, or starts from the booking event that changed them, as the no-show flow does.
- **Lost messages.** WeerOm tries a message 7 times over about 33 hours. A flow tool that was off for longer misses it. Run a scheduled flow once a day as well if nothing may be missed.
- **What a write can do.** The API makes, cancels and moves bookings and renames or blocks customers. It cannot note a payment, change a booking's service or make a customer without a booking.
- **One key per tool.** If the flow tool leaks the key, remove that one key in the admin and the rest keep working.


# Send payments to Billit

Source: https://developers.weerom.com/docs/use-cases/billit

> Turn every payment a shop notes in WeerOm into an invoice in Billit, from the payment.completed webhook or by polling the payments list.

**For** a shop that sends its invoices from Billit, or any other invoicing tool, and the developer or bookkeeper who connects the two.

A shop notes a payment in WeerOm when a customer pays at the chair. WeerOm does not take the money. It records the amount, the method and the moment. This job makes one invoice in Billit for each of those payments.

| What | You need |
| --- | --- |
| Key | **Read key** A read key, on a server. |
| Webhook | An address for **Payment noted**, which the shop adds in its admin. See [Webhooks](https://developers.weerom.com/docs/webhooks#add-an-address). Optional with polling. |
| Endpoints | `GET /payments`, `GET /shop` for the time zone, `GET /customers/{id}` for a postal code. |
| Billit | An account with API access. Billit documents its API at [docs.billit.be](https://docs.billit.be/docs/get-started). |

## Two ways to run it

| Way | How | Fits |
| --- | --- | --- |
| Webhook | WeerOm posts a `payment.completed` message to your server a few seconds after staff note a payment. | A server with a public HTTPS address. The invoice exists before the customer is out of the door. |
| Polling | A job asks `GET /payments?paid_after=...` every 15 minutes. | A script without a public address, or a shop that invoices once a day. |

Run both when no payment may be missed. The polling job catches a message your server lost while it was down for more than 33 hours. Both check the payment's `id` first, so a payment gets one invoice.

## What a payment holds

```json
{
  "object": "payment",
  "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
  "booking_id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
  "booking_code": "UEAMEFC9",
  "paid_at": "2026-11-21T10:12:40.000Z",
  "starts_at": "2026-11-21T09:30:00.000Z",
  "description": "Knippen en baard",
  "amount_cents": 4000,
  "list_price_cents": 4000,
  "discount_percent": 0,
  "net_cents": 3306,
  "vat_cents": 694,
  "vat_percent": 21,
  "tip_cents": 200,
  "currency": "EUR",
  "method": "bancontact",
  "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
  "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
  "customer": {
    "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
    "name": "Lotte Peeters",
    "email": "lotte@example.com",
    "phone": "+32470123456"
  }
}
```

## Map a payment to an invoice

The left column is the field in WeerOm. The right column says what it is for on the invoice. Take the field names for the right side from Billit's own API documentation. This page does not name them.

| Payment field | On the invoice |
| --- | --- |
| `id` | Your own record that this payment has an invoice. Store it, so you never invoice a payment twice. |
| `booking_code` | The reference on the invoice. Staff can find the booking in WeerOm by this code. |
| `paid_at` | The invoice date. Convert it from UTC to the shop's `time_zone` from `GET /shop` first, or a payment at 00:30 in Brussels lands on the day before. |
| `customer.name`, `customer.email` | Who the invoice is for. `customer.id` leads to `GET /customers/{id}`, which also has `postal_code`. |
| `description` | The text of the one invoice line: the service's name. |
| `net_cents` | The line's amount without VAT. |
| `vat_percent` | The line's VAT rate. `0` means the shop works under a VAT exemption. |
| `vat_cents` | The VAT on the line. `net_cents + vat_cents` is always `amount_cents`. |
| `amount_cents` | The total the customer paid for the service, VAT included. |
| `currency` | The invoice currency. |
| `method` | How the customer paid, such as `cash` or `bancontact`. Mark the invoice as paid with this method. `null` when staff did not say. |

Amounts are whole cents. Divide by 100 only when your tool wants euros, and round nowhere else: WeerOm has already split the total into net and VAT, rounding half up.

`tip_cents` is not part of `amount_cents`. Whether a tip belongs on the invoice is a question for the shop's accountant.

> **Read each payment soon after it is made.** WeerOm works out `net_cents` and `vat_cents` with the shop's VAT rate as it is set today. If the shop changes its rate, older payments read from then on split at the new rate. A job that runs every 15 minutes reads each payment long before that can happen.

## With the payment.completed webhook

The shop adds your address under **Updates for other software** and switches on **Payment noted**. Each message holds the payment in `data.object`, the same object as above. Your server checks the signature, stores the message and answers 200 within 10 seconds. A worker calls Billit afterwards.

```js title="billit-webhook.js"
// Node 22. verify() is the function from the Webhooks guide.
import { createServer } from "node:http";
import { verify } from "./verify.js";

const SECRET = process.env.WEEROM_WEBHOOK_SECRET;

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", async () => {
    const raw = Buffer.concat(chunks);
    if (!verify(raw, req.headers["weerom-signature"], SECRET)) {
      res.writeHead(400).end();
      return;
    }
    const message = JSON.parse(raw.toString("utf8"));
    if (message.type === "payment.completed") {
      await queuePayment(message.id, message.data.object);
    }
    // Answer 200 to the test message and to events you do not use, too.
    res.writeHead(200).end();
  });
}).listen(3000);

// The worker, run from your own queue.
export async function invoicePayment(eventId, payment) {
  // The same message can arrive twice. Skip an event you handled.
  if (await seenEvent(eventId)) return;

  if (await hasInvoice(payment.id)) {
    // Staff corrected a payment that already has an invoice.
    await askAPerson(payment);
  } else {
    await createBillitInvoice(payment);
  }
  await markSeen(eventId);
}
```

`queuePayment`, `seenEvent`, `hasInvoice`, `markSeen` and `askAPerson` stand for your own storage. [Webhooks](https://developers.weerom.com/docs/webhooks#verify-the-signature) has `verify()` in JavaScript, PHP and Python.

## The polling job

1. A job runs every 15 minutes.
2. It asks for payments noted since the last one it handled: `GET /payments?paid_after=...&order=asc`.
3. It makes an invoice for each new payment.
4. It remembers the `paid_at` of the last payment it handled, for the next run.

Pick any interval that suits the shop. A run with no new payments costs one request, so every 15 minutes is 4 requests an hour, far under the 120 a minute a key may make.

The sketch below is JavaScript for Node 22. It keeps its state in a small JSON file. `createBillitInvoice(payment)` stands for your own code that calls Billit with the mapping above. Fill it in from [Billit's API documentation](https://docs.billit.be/docs/get-started). Billit signs requests with OAuth 2.0 and has a sandbox at `api.sandbox.billit.be` for tests, according to its pages on [authentication](https://docs.billit.be/docs/authentication) and [sandbox and production](https://docs.billit.be/docs/sandbox-vs-production-1), read on 2026-11-21.

```js title="sync-payments.js"
import { readFile, writeFile } from "node:fs/promises";

const BASE = "https://api.weerom.com/v1";
const STATE_FILE = "./weerom-state.json";

// The first run starts here. Pick the moment the shop wants invoices from.
const START = "2026-12-01T00:00:00+01:00";

async function loadState() {
  try {
    return JSON.parse(await readFile(STATE_FILE, "utf8"));
  } catch {
    return { lastPaidAt: START, handled: [] };
  }
}

async function saveState(state) {
  await writeFile(STATE_FILE, JSON.stringify(state, null, 2));
}

async function getPage(cursor, since) {
  const url = new URL(`${BASE}/payments`);
  url.searchParams.set("paid_after", since);
  url.searchParams.set("order", "asc");
  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) {
    const { error } = await response.json();
    throw new Error(`${response.status} ${error.code}: ${error.message} (${error.request_id})`);
  }
  return response.json();
}

export async function syncPayments() {
  const state = await loadState();
  const since = state.lastPaidAt;
  let cursor = null;

  do {
    const page = await getPage(cursor, since);

    for (const payment of page.data) {
      // paid_after includes its own moment, so the last payment of the
      // previous run comes back once. Skip what already has an invoice.
      if (state.handled.includes(payment.id)) continue;

      await createBillitInvoice(payment);

      // Keep only the ids at the newest moment. Older ones cannot come back.
      if (payment.paid_at !== state.lastPaidAt) state.handled = [];
      state.handled.push(payment.id);
      state.lastPaidAt = payment.paid_at;
      await saveState(state);
    }

    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);
}

await syncPayments();
```

Run it every 15 minutes with cron, a scheduled function or your platform's job runner:

```txt
*/15 * * * * WEEROM_KEY=wo_live_... node sync-payments.js
```

## Details that matter

- **The time zone.** Read `GET /shop` once and keep its `time_zone`. The webhook does not carry it.
- **Ascending order.** `order=asc` hands you the oldest payment first. The job can then save `lastPaidAt` after each invoice, and a run that stops halfway picks up where it stopped.
- **The edge of `paid_after`.** `paid_after` returns payments noted at or after that moment. The last payment of one run comes back at the start of the next. The `handled` list catches it.
- **A crash between Billit and the state file.** If the job stops after Billit made the invoice but before `saveState`, the next run tries that payment again. Look for an invoice with that `booking_code` in Billit before you make another, or accept that this rare case needs a person.
- **Errors.** In the polling job, a 401 or 403 means the key was removed or the shop left Premium. Stop and tell someone. A 429 or 500 can wait for the next run. See [Errors](https://developers.weerom.com/docs/errors).
- **One key for this job.** Make a read key named "Billit" and use it only here. See [Authentication](https://developers.weerom.com/docs/authentication).
- **A corrected payment comes back.** When staff change the method or an amount of a payment they noted, `paid_at` moves to the moment of the change, and the payment shows up again in a later run with the same `id`. The webhook sends a new `payment.completed` message for it, with a new event `id` and the same `data.object.id`. The `handled` list of the polling job keeps only the newest ids, so it does not catch this. Keep every invoiced `id` in your own records, or look for the `booking_code` in Billit, and send a payment that comes back to a person: it may need a credit note.
- **Filter by method.** `GET /payments?method=cash` lists the payments of one method, for a shop that invoices those apart.

## Limits

The API cannot write back to WeerOm that a payment has an invoice, so the job keeps that record itself, in `handled`. It cannot note a payment either: staff note it in the admin, and the job reads it afterwards. A corrected payment comes back with a new `paid_at` and nothing says what changed, so the job cannot tell a correction from a new payment without its own records. A payment staff remove disappears from the list without a trace and sends no webhook. WeerOm does not take the money, so the API knows nothing about refunds.


# Your own booking page

Source: https://developers.weerom.com/docs/use-cases/booking-page

> A booking page in your own design on any site, with WeerOm's agenda, rules and mail behind it.

**For** a shop with its own site, or the agency that builds it, that wants booking to look and feel like the rest of the site instead of a link to another page.

The page reads the services and the free times from WeerOm and sends the booking to it. WeerOm checks the shop's rules, puts the booking in the agenda, mails the customer the shop's confirmation with a link to manage the booking, and tells staff. The page needs no database and, with a public key, no server.

| What | You need |
| --- | --- |
| Key | **Public key** A public key in the browser. **Write key** A write key if your server makes the calls. |
| Endpoints | `GET /shop`, `GET /services`, `GET /staff`, `GET /availability`, `POST /bookings`. |

## Steps

1. Read `GET /shop` for the time zone.
2. Let the customer pick a service from `GET /services?active=true`.
3. Show free times from `GET /availability`, for one staff member or for anyone.
4. Ask for name, phone and email, and send `POST /bookings` with an `Idempotency-Key`.
5. On `slot_taken`, ask for the free times again.

```js
const slots = await weerom(`/availability?service_id=${serviceId}&date=2026-11-30&days=7`);

const booking = await weerom("/bookings", {
  body: {
    customer: { email: "lotte@example.com", name: "Lotte Peeters", phone: "+32470123456" },
    service_id: slots.data[0].service_id,
    staff_id: slots.data[0].staff_id,
    starts_at: slots.data[0].starts_at,
  },
  idempotencyKey: crypto.randomUUID(),
});
```

[Build a booking page](https://developers.weerom.com/docs/booking-page) is the full guide: the helper behind `weerom()`, showing times on the shop's clock, every error and what the page shows for it.

## How often

The page asks when a customer looks, so there is nothing to poll. Each visitor costs a few requests: the shop, the services, a week of free times or two, one booking.

## Limits

- **A visitor's limits.** A public key allows 10 booking requests an hour from one address, as on the shop's own form. A page behind a proxy that sends every visitor from one address needs a write key on the server instead.
- **The staff list does not say who does which service.** Take the staff from the free times.
- **No deposit or payment.** WeerOm does not take money, and the API cannot ask for a deposit.
- **One service per booking.** `POST /bookings` takes one `service_id`. The API cannot book two services as one visit.


# Bookings in your calendar

Source: https://developers.weerom.com/docs/use-cases/calendar

> Copy every booking into Google Calendar or Outlook, update it when it moves and remove it when it is cancelled.

**For** a shop that plans in a shared Google or Outlook calendar, or an owner who wants every chair's day next to their own appointments.

WeerOm tells your server about each booking that is made, changed or cancelled, through webhooks. Your code writes each one to the calendar as an event, keyed by the booking's `id`, so a move updates the event instead of adding a second one. A cancelled booking removes its event. A job that asks every 5 minutes does the same where nobody can add a webhook address.

| What | You need |
| --- | --- |
| Key | **Read key** A read key, on a server. |
| Webhook | An address for **Booking made**, **Booking changed** and **Booking cancelled**, which the shop adds in its admin. See [Webhooks](https://developers.weerom.com/docs/webhooks#add-an-address). |
| Endpoints | `GET /bookings` for the first fill and for polling, `GET /staff` for names. |
| Calendar | Your own code that writes to Google Calendar or Outlook. |

> **One staff member's own agenda.** A staff member who only wants their own bookings on their phone needs no code. The admin has a calendar feed for each staff member under **Team**, **Barbers**, which any calendar app can subscribe to. Use the API when you want your own titles, one shared calendar, or a calendar you write to yourself.

## Steps

1. On the first run, read every booking from now on: `GET /bookings?starts_after=<now>&order=asc`.
2. Write each one to the calendar. Store the calendar's event id next to the booking `id`, or put the booking `id` in the event, so you can find the event again.
3. From then on, act on each webhook: update the event for `booking.created` and `booking.updated`, remove it for `booking.cancelled`.
4. Without webhooks, remember the highest `updated_at` you saw across all pages. Every 5 minutes, read `GET /bookings?updated_after=<that value>`, update each event, and remove the event of each booking with `status: "cancelled"`.

## What a booking holds

```json
{
  "object": "booking",
  "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
  "code": "UEAMEFC9",
  "status": "confirmed",
  "starts_at": "2026-11-21T09:30:00.000Z",
  "ends_at": "2026-11-21T10:15:00.000Z",
  "minutes": 45,
  "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
  "service": { "id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68", "name": "Knippen en baard" },
  "customer": { "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75", "name": "Lotte Peeters", "email": "lotte@example.com", "phone": "+32470123456" },
  "comments": "",
  "updated_at": "2026-11-18T14:02:11.000Z"
}
```

`starts_at` and `ends_at` are UTC, with the `Z` that says so. Pass them with that zone, or convert them to the shop's `time_zone` from `GET /shop`, whichever your calendar's API asks for.

## With webhooks

`upsertCalendarEvent(booking, staffName)` and `removeCalendarEvent(bookingId)` stand for your own code. Fill them in from the Google Calendar or Microsoft Graph documentation. This page does not describe either API.

Messages can arrive out of order: a retry of an older move can land after a newer one. Keep the `updated_at` you last wrote for each booking, and skip a message that is older.

```js title="calendar-webhook.js"
// Node 22. verify() is the function from the Webhooks guide.
import { createServer } from "node:http";
import { verify } from "./verify.js";

const SECRET = process.env.WEEROM_WEBHOOK_SECRET;
const EVENTS = ["booking.created", "booking.updated", "booking.cancelled"];

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", async () => {
    const raw = Buffer.concat(chunks);
    if (!verify(raw, req.headers["weerom-signature"], SECRET)) {
      res.writeHead(400).end();
      return;
    }
    const message = JSON.parse(raw.toString("utf8"));
    if (EVENTS.includes(message.type)) {
      await queueBooking(message.data.object);
    }
    res.writeHead(200).end();
  });
}).listen(3000);

// The worker, run from your own queue.
export async function applyBooking(booking, staffName) {
  const written = await lastWrittenAt(booking.id);
  if (written && written >= booking.updated_at) return; // older or the same

  if (booking.status === "cancelled") {
    await removeCalendarEvent(booking.id);
  } else {
    await upsertCalendarEvent(booking, staffName.get(booking.staff_id));
  }
  await rememberWrittenAt(booking.id, booking.updated_at);
}
```

The `updated_at` check also makes a message that arrives twice harmless. Read `GET /staff` once an hour for `staffName`: staff changes send no webhook.

## The polling job

```js title="sync-calendar.js"
import { readFile, writeFile } from "node:fs/promises";

const BASE = "https://api.weerom.com/v1";
const STATE_FILE = "./calendar-state.json";

async function weerom(path) {
  const response = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
  });
  const json = await response.json();
  if (!response.ok) {
    throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
  }
  return json;
}

async function loadState() {
  try {
    return JSON.parse(await readFile(STATE_FILE, "utf8"));
  } catch {
    return { lastUpdatedAt: null };
  }
}

export async function syncCalendar() {
  const state = await loadState();
  const staff = await weerom("/staff");
  const staffName = new Map(staff.data.map((person) => [person.id, person.name]));

  let highest = state.lastUpdatedAt;
  let cursor = null;
  do {
    const query = new URLSearchParams({ limit: "100", order: "asc" });
    if (state.lastUpdatedAt) {
      // A minute of overlap. An event written twice is the same event.
      const since = new Date(Date.parse(state.lastUpdatedAt) - 60_000);
      query.set("updated_after", since.toISOString());
    } else {
      query.set("starts_after", new Date().toISOString());
    }
    if (cursor) query.set("cursor", cursor);
    const page = await weerom(`/bookings?${query}`);

    for (const booking of page.data) {
      if (booking.status === "cancelled") {
        await removeCalendarEvent(booking.id);
      } else {
        await upsertCalendarEvent(booking, staffName.get(booking.staff_id));
      }
      if (!highest || booking.updated_at > highest) highest = booking.updated_at;
    }
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  await writeFile(STATE_FILE, JSON.stringify({ lastUpdatedAt: highest }));
}

await syncCalendar();
```

Two details:

- The list stays sorted by `starts_at` even with `updated_after`, so the job takes the highest `updated_at` from every page, not from the last one.
- `updated_after` leaves out a booking changed at exactly that moment. The minute of overlap catches it, and the upsert by `id` makes a second write harmless.

## How often

With webhooks, an event moves a few seconds after the booking does. Run the polling job once a night as well, to catch a message your server lost while it was down for more than 33 hours.

Without webhooks, every 5 minutes. A quiet run is 2 requests, one for the staff and one for the bookings. That is 24 requests an hour, against 120 a minute for the key. A shop's day rarely changes faster than that. Run it every minute if the shop wants it sooner, at 2 requests a minute.

## Limits

- **One way.** An event moved in Google Calendar or Outlook stays where WeerOm had it on the next change. A write key could move the booking with `POST /bookings/{id}/reschedule`, but deciding which side wins is yours to build.
- **No breaks.** Time staff blocked off is not a booking, and the API leaves it out.
- **Customer details in a calendar.** Every event holds a customer's name and phone if you put them there. Share that calendar only with people who may see them.


# Overview

Source: https://developers.weerom.com/docs/use-cases

> Ten things people build on the WeerOm API, each with the key it needs, the steps, a code sketch and what the API cannot do for it.

Each use case names who it is for, the endpoints and the kind of key, the steps, a short sketch in JavaScript, and its limits. The sketches call only real WeerOm endpoints and fields. Where another product comes in, a named function such as `createBillitInvoice(payment)` stands for your own code, which you write from that product's documentation.

- [Send payments to Billit](https://developers.weerom.com/docs/use-cases/billit.md): Make one invoice in Billit for every payment staff note in WeerOm. Keys: Read key.
- [Bookkeeping with Accountable](https://developers.weerom.com/docs/use-cases/accountable.md): Build the admin's Accountable lines from the payments: one per day and payment method. Keys: Read key.
- [Your own booking page](https://developers.weerom.com/docs/use-cases/booking-page.md): Your own design on any site, with WeerOm's agenda, rules and mail behind it. Keys: Public key, Write key.
- [Bookings in your calendar](https://developers.weerom.com/docs/use-cases/calendar.md): Copy every booking into Google Calendar or Outlook and keep the copy current. Keys: Read key.
- [Customers in a mailing tool](https://developers.weerom.com/docs/use-cases/newsletter.md): Keep a Mailchimp or Brevo list in step with the shop's customers. Keys: Read key.
- [A revenue sheet](https://developers.weerom.com/docs/use-cases/revenue-sheet.md): Revenue per day, per staff member and per payment method in Google Sheets. Keys: Read key.
- [Automations](https://developers.weerom.com/docs/use-cases/automations.md): A flow in n8n, Make or Zapier, started by a WeerOm webhook or on a schedule. Keys: Read key, Write key.
- [Messages by SMS or WhatsApp](https://developers.weerom.com/docs/use-cases/messages.md): Send tomorrow's customers a text or a WhatsApp message through your own provider. Keys: Read key.
- [An assistant that books](https://developers.weerom.com/docs/use-cases/assistant.md): A chat or phone assistant that finds free times and books them from your server. Keys: Write key.
- [Several shops on one screen](https://developers.weerom.com/docs/use-cases/several-shops.md): One key for each shop and one loop, for an owner with two shops or a group. Keys: Read key.

## The kinds of key

| Key | Starts with | Use it for |
| --- | --- | --- |
| **Read key** | `wo_live_` | A server that reads: invoices, bookkeeping, calendars, sheets, dashboards. |
| **Write key** | `wo_live_` | A server that also books, cancels, moves or blocks. |
| **Public key** | `wo_pub_` | A booking page in the browser. |

[Authentication](https://developers.weerom.com/docs/authentication) says what each may do and how a shop makes one.

## Following changes

A use case that follows changes can hear about them in two ways.

- **Webhooks.** WeerOm posts a signed message to your server a few seconds after a booking is made, changed or cancelled, or a payment is noted. The invoices, the calendar, the reminders and the automations use them. See [Webhooks](https://developers.weerom.com/docs/webhooks).
- **Polling.** A job asks on a schedule, with `updated_after` on bookings and customers or `paid_after` on payments. One run that finds nothing costs one request. At 120 requests a minute for each key, a job every 5 or 15 minutes uses a small part of it. Customers send no webhook, so the newsletter polls. The revenue sheet polls because once an hour is enough.

Where both fit, each page says which to pick.


# Messages by SMS or WhatsApp

Source: https://developers.weerom.com/docs/use-cases/messages

> Read tomorrow's bookings once a day and send each customer a reminder by SMS or WhatsApp. Webhooks cover bookings made after the daily run.

**For** a shop whose customers read texts more than mail, and that already has an account with an SMS or WhatsApp provider.

Every evening at 18:00, a job reads tomorrow's confirmed bookings and sends each customer one message with the time and the service. WeerOm already sends a reminder by mail. This adds one on the phone, through a provider the shop chose and pays.

| What | You need |
| --- | --- |
| Key | **Read key** A read key, on a server. |
| Endpoints | `GET /shop` for the time zone and name, `GET /bookings` with `starts_after`, `starts_before` and `status`. |
| Webhook | Optional. An address for **Booking made** and **Booking changed**, for bookings made or moved after the run. See [Webhooks](https://developers.weerom.com/docs/webhooks#add-an-address). |
| Provider | An SMS or WhatsApp provider with an API, and your own code that sends through it. |

## Steps

1. Read the shop for its `time_zone` and `name`.
2. Work out tomorrow's date on the shop's clock.
3. Read the confirmed bookings that start tomorrow.
4. Send one message per booking. Remember which booking ids got one, so a second run sends nothing twice.

## The job

`sendMessage(phone, text)` stands for your own code. Fill it in from your provider's API documentation. This page does not describe any provider's API.

```js title="remind.js"
import { readFile, writeFile } from "node:fs/promises";

const BASE = "https://api.weerom.com/v1";
const SENT_FILE = "./sent.json";

async function weerom(path) {
  const response = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
  });
  const json = await response.json();
  if (!response.ok) {
    throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
  }
  return json;
}

const addDays = (day, days) => {
  const date = new Date(`${day}T00:00:00Z`);
  date.setUTCDate(date.getUTCDate() + days);
  return date.toISOString().slice(0, 10);
};

const shop = await weerom("/shop");
const dayIn = new Intl.DateTimeFormat("en-CA", { timeZone: shop.time_zone });
const clock = new Intl.DateTimeFormat("nl-BE", {
  hour: "2-digit",
  minute: "2-digit",
  timeZone: shop.time_zone,
});

const tomorrow = addDays(dayIn.format(new Date()), 1);
const sent = new Set(await readFile(SENT_FILE, "utf8").then(JSON.parse, () => []));

// A day wider on both sides, then keep tomorrow on the shop's own clock.
const query = new URLSearchParams({
  limit: "100",
  order: "asc",
  starts_after: `${addDays(tomorrow, -1)}T00:00:00Z`,
  starts_before: `${addDays(tomorrow, 2)}T00:00:00Z`,
  status: "confirmed",
});

let cursor = null;
do {
  if (cursor) query.set("cursor", cursor);
  const page = await weerom(`/bookings?${query}`);

  for (const booking of page.data) {
    const startsAt = new Date(booking.starts_at);
    if (dayIn.format(startsAt) !== tomorrow) continue;
    if (!booking.customer.phone || sent.has(booking.id)) continue;

    const text = `${shop.name}: tot morgen om ${clock.format(startsAt)} voor ${booking.service.name}. Code ${booking.code}.`;
    await sendMessage(booking.customer.phone, text);
    sent.add(booking.id);
    await writeFile(SENT_FILE, JSON.stringify([...sent]));
  }
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);
```

The message reads "Studio Noord: tot morgen om 10:30 voor Knippen en baard. Code UEAMEFC9." `customer.phone` is in E.164, with the country code: `+32470123456`. The field can be `null`, and the job skips those bookings.

Run it once a day at 18:00:

```txt
0 18 * * * WEEROM_KEY=wo_live_... node remind.js
```

The cron runs on the server's clock. Set the server to the shop's zone, or move the hour.

## Bookings made after the run

A booking made at 20:00 for tomorrow morning misses the 18:00 run. A webhook catches it. Let the shop add your address for **Booking made** and **Booking changed**, and send the reminder at once when a booking lands in tomorrow after the run:

```js title="remind-webhook.js"
// Called from your webhook server once verify() passed. See the Webhooks guide.
export async function onBookingMessage(message) {
  if (message.type !== "booking.created" && message.type !== "booking.updated") return;
  const booking = message.data.object;
  if (booking.status !== "confirmed" || !booking.customer.phone) return;

  const tomorrow = addDays(dayIn.format(new Date()), 1);
  const ranToday = new Date().getHours() >= 18; // on the shop's clock
  if (!ranToday || dayIn.format(new Date(booking.starts_at)) !== tomorrow) return;
  if (await alreadySent(booking.id)) return;

  await sendMessage(booking.customer.phone, reminderText(booking));
  await markSent(booking.id);
}
```

`alreadySent` and `markSent` read and write the same record as the daily job, so a booking never gets two reminders. A booking moved to another time after its reminder went out keeps the old text. Send a second message for that case if the shop wants one.

## How often

Once a day. A day of 40 bookings is 2 requests. The job does not need to poll: tomorrow's list at 18:00 is the list, and the webhook covers what comes after. Without the webhook, a booking made after 18:00 for tomorrow gets the shop's mail reminder only.

## Limits

- **One language in the sketch.** The sketch writes Dutch. Each booking has `locale`, the language its mail goes out in. Pick the text by it.
- **No opt-out in WeerOm.** The API does not say whether a customer wants texts. The shop keeps that record, and the provider's own rules apply. WhatsApp has rules for messages a business starts. We did not check them: read your provider's documentation.
- **No reply into WeerOm.** A customer who answers "cancel" reaches your provider, not the agenda. A write key could cancel with `POST /bookings/{id}/cancel`, but reading the reply is yours to build. The manage link in the shop's confirmation mail already lets the customer cancel.


# Customers in a mailing tool

Source: https://developers.weerom.com/docs/use-cases/newsletter

> Keep a Mailchimp or Brevo list in step with the shop's customers, and only mail the ones who agreed.

**For** a shop that sends a newsletter or a campaign from Mailchimp, Brevo or a CRM, and wants new customers to show up there without a weekly export.

A job reads the customers that changed since its last run and adds or updates each one as a contact, keyed by the customer's `id`. It sends name, email, language and postal code. Whether a person may get marketing mail is the shop's to know: the API does not say.

| What | You need |
| --- | --- |
| Key | **Read key** A read key, on a server. |
| Endpoints | `GET /customers` with `updated_after`. |
| Mailing tool | Your own code that adds a contact in Mailchimp, Brevo or your CRM. |

> **The API does not say who agreed to mail.** A customer object has no mail preference and no consent. WeerOm leaves its own mail preferences out of the API on purpose. A customer who booked a haircut did not, by booking, agree to a newsletter. The shop must have its own consent, under the GDPR, before it mails anyone, for example from a sign-up form on its site. Add customers to the tool as contacts without a subscription, and mark only the ones who agreed as subscribed.

## What a customer holds

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

| Field | In the mailing tool |
| --- | --- |
| `id` | Your own key for the contact. A customer's email may change, the `id` does not. |
| `email` | The address. `null` for a customer who booked without one: skip them. |
| `name` | One field. WeerOm does not split first and last name. |
| `locale` | The language their mail from the shop goes out in. Use it to pick the campaign's language. |
| `postal_code` | For a campaign by area. `null` when unknown. |
| `blocked` | The shop stopped taking online bookings from them. You may want to leave them out. |

## The job

`upsertContact(customer)` stands for your own code. Fill it in from Mailchimp's or Brevo's own API documentation. This page does not describe either API.

```js title="sync-contacts.js"
import { readFile, writeFile } from "node:fs/promises";

const BASE = "https://api.weerom.com/v1";
const STATE_FILE = "./contacts-state.json";

async function weerom(path) {
  const response = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
  });
  const json = await response.json();
  if (!response.ok) {
    throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
  }
  return json;
}

const state = await readFile(STATE_FILE, "utf8").then(JSON.parse, () => ({ lastUpdatedAt: null }));
let highest = state.lastUpdatedAt;
let cursor = null;

do {
  const query = new URLSearchParams({ limit: "100", order: "asc" });
  if (state.lastUpdatedAt) query.set("updated_after", state.lastUpdatedAt);
  if (cursor) query.set("cursor", cursor);
  const page = await weerom(`/customers?${query}`);

  for (const customer of page.data) {
    if (customer.email) {
      // As a contact, not as a subscriber. Consent comes from the shop.
      await upsertContact({
        email: customer.email,
        externalId: customer.id,
        language: customer.locale,
        name: customer.name,
        postalCode: customer.postal_code,
      });
    }
    if (!highest || customer.updated_at > highest) highest = customer.updated_at;
  }
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

await writeFile(STATE_FILE, JSON.stringify({ lastUpdatedAt: highest }));
```

The first run reads every customer. A shop with 3,000 customers is 30 requests. The list is sorted by `created_at`, so take the highest `updated_at` from all pages, as the job does.

## How often

Once an hour, or once a night. A newsletter does not need a customer the minute they booked. A quiet run is one request. A change to a customer sends no webhook, so the job asks.

## Limits

- **No consent and no mail preferences.** The API does not expose them. The shop keeps its own record of who agreed.
- **No unsubscribes back.** Someone who unsubscribes in Mailchimp or Brevo stays a customer in WeerOm, and WeerOm's own booking mail keeps going to them. The two lists are separate.
- **No deletions.** A customer the shop erased does not show up as a change. Walk the whole list now and then and remove contacts whose `id` is gone.
- **One-way.** `PATCH /customers/{id}` changes only a name or a block, so the mailing tool cannot write an email or a phone back to WeerOm.


# A revenue sheet

Source: https://developers.weerom.com/docs/use-cases/revenue-sheet

> Revenue per day, per staff member and per payment method in Google Sheets, refreshed every hour by Apps Script.

**For** an owner who runs the numbers in a spreadsheet: who earned what this month, how much came in as cash, how a Saturday compares to a Tuesday.

A script inside the spreadsheet reads the last 31 days of payments every hour and writes one row per day, staff member and payment method. A pivot table or a chart on top of that row data answers the questions. Nothing runs outside Google.

| What | You need |
| --- | --- |
| Key | **Read key** A read key, kept in the script's properties. |
| Endpoints | `GET /shop` for the time zone, `GET /staff` for names, `GET /payments`. |
| Google | A spreadsheet and its Apps Script editor, under **Extensions**, **Apps Script**. |

The script uses Apps Script's [`UrlFetchApp.fetch`](https://developers.google.com/apps-script/reference/url-fetch/url-fetch-app) to call WeerOm and a [time-driven trigger](https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers) to run every hour. We read both pages on 2026-11-21.

## Steps

1. In the spreadsheet, open **Extensions**, **Apps Script**, and paste the script below.
2. Under **Project settings**, add a script property `WEEROM_KEY` with the read key. The key stays out of the code and out of the sheet.
3. Run `updateRevenue` once and allow the script to reach an outside service.
4. Under **Triggers**, add a time-driven trigger for `updateRevenue`, every hour.
5. Insert a pivot table on the `WeerOm` sheet: rows by `day`, `staff` or `method`, values as the sum of `amount`.

## The script

```js title="Code.gs"
const BASE = "https://api.weerom.com/v1";
const DAYS = 31;

function weerom(path) {
  const key = PropertiesService.getScriptProperties().getProperty("WEEROM_KEY");
  const response = UrlFetchApp.fetch(BASE + path, {
    headers: { Authorization: `Bearer ${key}` },
    muteHttpExceptions: true,
  });
  const json = JSON.parse(response.getContentText());
  if (response.getResponseCode() !== 200) {
    throw new Error(`${json.error.code}: ${json.error.message} (${json.error.request_id})`);
  }
  return json;
}

function updateRevenue() {
  const shop = weerom("/shop");
  const staffName = {};
  for (const person of weerom("/staff").data) staffName[person.id] = person.name;

  const since = new Date(Date.now() - DAYS * 24 * 60 * 60 * 1000).toISOString();
  const totals = {};
  let cursor = null;

  do {
    let path = `/payments?limit=100&order=asc&paid_after=${encodeURIComponent(since)}`;
    if (cursor) path += `&cursor=${encodeURIComponent(cursor)}`;
    const page = weerom(path);

    for (const payment of page.data) {
      const day = Utilities.formatDate(new Date(payment.paid_at), shop.time_zone, "yyyy-MM-dd");
      const staff = staffName[payment.staff_id] || payment.staff_id;
      const method = payment.method || "not noted";
      const key = [day, staff, method].join("|");
      const row = totals[key] || { amount: 0, count: 0, day, method, net: 0, staff, tips: 0, vat: 0 };
      row.count += 1;
      row.amount += payment.amount_cents;
      row.net += payment.net_cents;
      row.vat += payment.vat_cents;
      row.tips += payment.tip_cents;
      totals[key] = row;
    }
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  const rows = [["day", "staff", "method", "payments", "amount", "net", "vat", "tips"]];
  for (const row of Object.values(totals).sort((a, b) => (a.day + a.staff).localeCompare(b.day + b.staff))) {
    rows.push([row.day, row.staff, row.method, row.count, row.amount / 100, row.net / 100, row.vat / 100, row.tips / 100]);
  }

  const book = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = book.getSheetByName("WeerOm") || book.insertSheet("WeerOm");
  sheet.clearContents();
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
}
```

Amounts land in the sheet as euros, so a sum or a chart works on them as they are. `amount` includes VAT. `tips` is apart from `amount`.

## How often

Every hour. A busy shop has a few hundred payments in 31 days: 2 requests for the shop and the staff, and 3 to 6 pages of payments. That is under 10 requests an hour. A sheet that shows a total does not need each payment within seconds, so it polls. For a live total, a `payment.completed` [webhook](https://developers.weerom.com/docs/webhooks) can add each payment as it comes, but the sheet then needs a web app address the shop can add, and a payment staff remove sends nothing.

## In Excel

Run the [Accountable script](https://developers.weerom.com/docs/use-cases/accountable), or this loop in Node with `fetch` in place of `UrlFetchApp`, on a schedule, and open the CSV it writes. This page does not cover Excel's own ways of calling a web address.

## Limits

- **Paid cuts only.** A booking without a noted payment is not in `GET /payments`. For booked revenue still to come, read `GET /bookings?status=confirmed` and sum `price_cents`.
- **No expenses.** The API does not expose the shop's expenses, so profit stays in the admin, under **Insights**, **Profit**.
- **Today's VAT rate.** `net_cents` and `vat_cents` use the shop's VAT rate as it is set today, for old payments too.
- **A rolling window.** The sheet holds the last 31 days and rewrites them each hour. To keep a year, raise `DAYS`, or copy each finished month to its own sheet.


# Several shops on one screen

Source: https://developers.weerom.com/docs/use-cases/several-shops

> One key for each shop and one loop over them, for an owner with two shops or a group's dashboard.

**For** an owner with two or more shops on WeerOm, or a group or franchise that wants one dashboard with every shop's day on it.

A key belongs to one shop. So the dashboard holds one read key per shop and runs the same requests for each: today's revenue, today's bookings, the payment methods. It shows the shops side by side and adds them up.

| What | You need |
| --- | --- |
| Keys | **Read key** One read key for each shop, each made by an administrator of that shop. |
| Endpoints | `GET /shop`, `GET /payments`, `GET /bookings`, for each key. |
| Dashboard | Your own page or tool that shows the numbers. |

Each shop must be on the Premium plan. A key of a shop that leaves Premium answers 403 `plan_required`, and the loop should show that shop as paused instead of stopping.

## The loop

```js title="shops.js"
const BASE = "https://api.weerom.com/v1";

// One read key for each shop, from your secret store.
const KEYS = [process.env.WEEROM_KEY_NOORD, process.env.WEEROM_KEY_ZUID];

async function weerom(key, path) {
  const response = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${key}` },
  });
  const json = await response.json();
  if (!response.ok) throw new Error(`${response.status} ${json.error.code}`);
  return json;
}

const addDays = (day, days) => {
  const date = new Date(`${day}T00:00:00Z`);
  date.setUTCDate(date.getUTCDate() + days);
  return date.toISOString().slice(0, 10);
};

async function today(key) {
  const shop = await weerom(key, "/shop");
  const dayIn = new Intl.DateTimeFormat("en-CA", { timeZone: shop.time_zone });
  const day = dayIn.format(new Date());
  // A day wider on both sides, then keep today on this shop's own clock.
  const from = `${addDays(day, -1)}T00:00:00Z`;
  const until = `${addDays(day, 2)}T00:00:00Z`;

  const totals = { bookings: 0, byMethod: {}, cancelled: 0, revenueCents: 0, tipsCents: 0 };

  let cursor = null;
  do {
    const query = new URLSearchParams({ limit: "100", paid_after: from, paid_before: until });
    if (cursor) query.set("cursor", cursor);
    const page = await weerom(key, `/payments?${query}`);
    for (const payment of page.data) {
      if (dayIn.format(new Date(payment.paid_at)) !== day) continue;
      totals.revenueCents += payment.amount_cents;
      totals.tipsCents += payment.tip_cents;
      const method = payment.method ?? "not noted";
      totals.byMethod[method] = (totals.byMethod[method] ?? 0) + payment.amount_cents;
    }
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  cursor = null;
  do {
    const query = new URLSearchParams({ limit: "100", starts_after: from, starts_before: until });
    if (cursor) query.set("cursor", cursor);
    const page = await weerom(key, `/bookings?${query}`);
    for (const booking of page.data) {
      if (dayIn.format(new Date(booking.starts_at)) !== day) continue;
      if (booking.status === "cancelled") totals.cancelled += 1;
      else totals.bookings += 1;
    }
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  return { currency: shop.currency, name: shop.name, ...totals };
}

const shops = await Promise.allSettled(KEYS.map(today));
for (const result of shops) {
  if (result.status === "rejected") {
    console.log(`A shop did not answer: ${result.reason.message}`);
    continue;
  }
  const shop = result.value;
  console.log(`${shop.name}: €${shop.revenueCents / 100}, ${shop.bookings} bookings, ${shop.cancelled} cancelled`);
}
```

The shops run side by side with `Promise.allSettled`, so one shop with a removed key does not hide the others. Each shop answers in its own `currency` and its own `time_zone`. Shops in Belgium and Portugal have different clocks, and the loop works out "today" for each.

## How often

Every 5 minutes for a screen on the wall. Each shop costs 3 requests a run on a normal day: the shop, one page of payments, one page of bookings. The limit of 120 a minute is per key, so ten shops do not share one budget.

## Limits

- **One key per shop.** There is no group key that reads several shops. Someone with administrator rights in each shop makes that shop's key, and each one can be removed on its own.
- **Names do not line up.** Staff and service ids belong to one shop. The same person working in two shops is two staff members with two ids. Match them by name if you must.
- **Webhooks name no shop.** A webhook message carries the booking or the payment, not the shop it came from. Give each shop its own address, such as `https://example.com/weerom/noord` and `https://example.com/weerom/zuid`, and check each message with that shop's secret. See [Webhooks](https://developers.weerom.com/docs/webhooks).
- **Today's VAT rate.** For a dashboard that splits out VAT, `net_cents` and `vat_cents` use each shop's rate as it is set today.


# Webhooks

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

> WeerOm posts a signed JSON message to your server when a booking is made, changed or cancelled, or a payment is noted. Verify it, answer 2xx, then work.

A webhook is a POST from WeerOm to your server. When a booking is made, changed or cancelled, or staff note a payment, WeerOm sends a JSON message to every address the shop added for that event. The message holds the whole booking or payment, as `GET /bookings/{id}` or `GET /payments/{id}` would answer at that moment.

With webhooks, an invoice can exist a few seconds after the customer paid, and a calendar moves the moment the booking does. Without them, your job asks the API on a schedule. [Polling](#polling-as-the-fallback) below says when that still fits.

## Add an address

The shop adds the address in its admin. There is no API endpoint for it, so you give the shop the address and the shop gives you the secret.

1. You run an HTTPS endpoint, such as `https://example.com/weerom/webhooks`, that follows [the rules for an address](#rules-for-an-address).
2. An administrator of the shop opens **Settings**, then **Features**, then **Connections**, and scrolls to **Updates for other software**.
3. They paste your address under **Web address**, switch on the updates you need, and press **Add the address**.
4. The admin shows the **Secret** once. It starts with `whsec_`. They copy it to you, and you store it like a password: in an environment variable or a secret store, never in source code.
5. They press **Send a test**. Your endpoint gets a [test message](#the-test-message), and the admin says whether it answered.

A shop holds up to 5 addresses. Each address has its own secret and its own set of events. The shop must be on the Premium plan, the same as for keys. A shop that leaves Premium keeps its addresses but sends nothing until it is back.

Each address can be switched off and on in the same place. Removing it stops every message at once and cannot be undone. A new address gets a new secret.

## Events

| Event | The admin calls it | WeerOm sends it when |
| --- | --- | --- |
| `booking.created` | Booking made | A booking is made: online, by staff in the agenda, or through `POST /bookings`. |
| `booking.updated` | Booking changed | A booking moves to another time or staff member, changes service, or staff mark it completed, a no-show or open again. |
| `booking.cancelled` | Booking cancelled | A booking is cancelled, by the customer, by staff or through `POST /bookings/{id}/cancel`. |
| `payment.completed` | Payment noted | Staff note a payment, or change the method or an amount of a payment they noted earlier. |

What sends nothing:

- Time staff block off for a break. It is not a booking.
- A cancellation sends `booking.cancelled` only, never `booking.updated` as well.
- Noting a payment sends `payment.completed` only. The booking's `payment` field changes, but no `booking.updated` goes out.
- Staff clearing a payment, or saving one again without a change.
- A change to a customer. Read those with `GET /customers?updated_after=...`.

## The message

Every message has the same four fields:

| Field | Meaning |
| --- | --- |
| `id` | The event's id: `evt_` and 32 hex characters. Every address that gets this event sees the same `id`, and a retry keeps it. |
| `type` | The event, such as `booking.created`, or `test`. |
| `created_at` | When the event happened, ISO 8601 in UTC. |
| `data.object` | The booking or the payment, as the API answers it at that moment. [Get a booking](https://developers.weerom.com/docs/reference/bookings/getBooking) and [Get a payment](https://developers.weerom.com/docs/reference/payments/getPayment) describe every field. |

WeerOm writes the body once, on one line, and sends those exact bytes on every attempt. The examples below have line breaks added.

### booking.created

```json
{
  "created_at": "2026-11-18T14:02:11.412Z",
  "data": {
    "object": {
      "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": null,
      "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": "confirmed",
      "updated_at": "2026-11-18T14:02:11.000Z"
    }
  },
  "id": "evt_3f9a1c2e5b7d4a68c0e1f2a3b4c5d6e7",
  "type": "booking.created"
}
```

`booking.updated` and `booking.cancelled` carry the same booking object, with the new `starts_at`, `staff_id`, `status` or `cancelled_at`.

### payment.completed

```json
{
  "created_at": "2026-11-21T10:12:40.517Z",
  "data": {
    "object": {
      "amount_cents": 4000,
      "booking_code": "UEAMEFC9",
      "booking_id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
      "currency": "EUR",
      "customer": {
        "email": "lotte@example.com",
        "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
        "name": "Lotte Peeters",
        "phone": "+32470123456"
      },
      "description": "Knippen en baard",
      "discount_percent": 0,
      "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
      "list_price_cents": 4000,
      "method": "bancontact",
      "net_cents": 3306,
      "object": "payment",
      "paid_at": "2026-11-21T10:12:40.000Z",
      "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
      "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
      "starts_at": "2026-11-21T09:30:00.000Z",
      "tip_cents": 200,
      "vat_cents": 694,
      "vat_percent": 21
    }
  },
  "id": "evt_8b2e4d6f1a3c5e7092b4d6f8a1c3e5f7",
  "type": "payment.completed"
}
```

A payment's `id` is its booking's id. When staff correct a payment, a second `payment.completed` arrives with the same `data.object.id`, a later `paid_at` and the new amounts. Treat it as a change to the payment you already have, not as a new one.

## Headers

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `WeerOm-Webhooks/1` |
| `WeerOm-Event` | The event, such as `payment.completed`, or `test`. |
| `WeerOm-Delivery` | The id of this delivery to this address, a UUID. A retry keeps it. |
| `WeerOm-Signature` | `t=<unix seconds>,v1=<signature>`. See below. |

## Verify the signature

Anyone can send a POST to your address. The signature proves that WeerOm sent the message and that nobody changed it on the way.

`WeerOm-Signature` holds two parts. `t` is the moment of this attempt in Unix seconds. `v1` is the HMAC-SHA256, in lowercase hex, of `t`, a dot and the raw body, with the whole secret as the key, `whsec_` included.

To check a message:

1. Read the raw body as bytes, before any JSON parser touches it. A parsed and re-written body has other bytes and fails the check.
2. Split the header on `,` and each part on the first `=`, to get `t` and `v1`.
3. Refuse the message when `t` is more than 300 seconds from your clock. A message someone recorded and sends again later fails here.
4. Compute the HMAC-SHA256 of `<t>.<raw body>` with the secret, as hex.
5. Compare it with `v1` in constant time, with `timingSafeEqual`, `hash_equals` or `hmac.compare_digest`. A plain `==` stops at the first wrong character, and the time it takes tells an attacker how much of the signature was right.

Only parse the JSON once all of that passed.

```js tab="JavaScript"
// Node 22, no packages. Run with WEEROM_WEBHOOK_SECRET=whsec_... node webhooks.js
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const SECRET = process.env.WEEROM_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;

export function verify(rawBody, header, secret, nowMs = Date.now()) {
  const parts = {};
  for (const part of (header ?? "").split(",")) {
    const at = part.indexOf("=");
    if (at > 0) parts[part.slice(0, at)] = part.slice(at + 1);
  }
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(nowMs / 1000 - t) > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", secret)
    .update(`${t}.`)
    .update(rawBody)
    .digest();
  const given = Buffer.from(parts.v1, "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", async () => {
    const raw = Buffer.concat(chunks);
    if (!verify(raw, req.headers["weerom-signature"], SECRET)) {
      res.writeHead(400).end();
      return;
    }
    const message = JSON.parse(raw.toString("utf8"));
    // Store it and answer. Do the slow work later, from your own queue.
    await saveMessage(message);
    res.writeHead(200).end();
  });
}).listen(3000);
```

```php tab="PHP"
<?php
// PHP 8. Point your web server at this file.
const TOLERANCE_SECONDS = 300;

function weeromVerify(string $rawBody, string $header, string $secret): bool
{
    $parts = [];
    foreach (explode(',', $header) as $part) {
        $pair = explode('=', $part, 2);
        if (count($pair) === 2) {
            $parts[$pair[0]] = $pair[1];
        }
    }
    if (!isset($parts['t'], $parts['v1']) || !ctype_digit($parts['t'])) {
        return false;
    }
    if (abs(time() - (int) $parts['t']) > TOLERANCE_SECONDS) {
        return false;
    }
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_WEEROM_SIGNATURE'] ?? '';

if (!weeromVerify($raw, $header, getenv('WEEROM_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit;
}

$message = json_decode($raw, true);
// Store it and answer. Do the slow work later, from your own queue.
saveMessage($message);
http_response_code(200);
```

```python tab="Python"
# Python 3 with Flask: pip install flask
import hashlib
import hmac
import os
import time

from flask import Flask, request

SECRET = os.environ["WEEROM_WEBHOOK_SECRET"]
TOLERANCE_SECONDS = 300

app = Flask(__name__)

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1:
        return False
    if abs(time.time() - int(t)) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(
        secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, v1)

@app.post("/weerom/webhooks")
def weerom_webhooks():
    raw = request.get_data()
    if not verify(raw, request.headers.get("WeerOm-Signature", ""), SECRET):
        return "", 400
    # Store it and answer. Do the slow work later, from your own queue.
    save_message(request.get_json())
    return "", 200
```

`saveMessage(message)` and `save_message(message)` stand for your own code: a row in a table or a job in a queue.

### Check your code

These values give a known signature. Your `verify` should return true for them when you pass `t` as the current time, and false once you change one character of the body.

| Input | Value |
| --- | --- |
| Secret | `whsec_5c1e9a7f3b2d4c6e8a0f1b3d5e7c9a2b4d6f8e0a1c3b5d7f9e2a4c6b8d0f1e3a` |
| Body | `{"created_at":"2026-11-22T09:00:00.000Z","data":{"object":{"object":"test"}},"id":"evt_c4e6a8b0d2f41a3c5e7b9d1f3a5c7e9b","type":"test"}` |
| Header | `t=1795338000,v1=732c16f54332b87717f1cd6dbe9183242de7ad029c2bc36d9b6a059b36a503f6` |

`1795338000` is 2026-11-22 09:00 UTC, so the age check refuses it on any other day. Skip that one check while you test with it.

## Answer fast, then do the work

- Any 2xx status counts as delivered. WeerOm never reads the body of your answer.
- An attempt that gets no answer within 10 seconds counts as failed, even when your server finishes the work later.
- A redirect counts as failed. WeerOm does not follow it, so give the shop the final address.
- Store the message, answer 200, and do the slow part, such as calling Billit or Google Calendar, from your own queue afterwards.

## Retries

The first attempt runs right after the change. When it fails, WeerOm tries again on this schedule:

| Attempt | Waits after the attempt before |
| --- | --- |
| 1 | None. It runs a moment after the change. |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 24 hours |

Retries run once a minute and send up to 25 messages per shop per run, so a retry can start a minute or more after its time. After the seventh failure, about 33 hours after the change, WeerOm gives up on that message. It does not send it again, and there is no way to ask for it later. Read what you missed from the API: see [polling](#polling-as-the-fallback).

## The same message twice, and the order

Most messages arrive once. A few arrive twice: when your server did the work but answered after 10 seconds, or when WeerOm stopped between sending and noting your answer. Store each `id` you handled and skip one you have seen.

Messages can also arrive out of order. A retry of an older change can land after a newer one. Compare `data.object.updated_at` for a booking, or `data.object.paid_at` for a payment, with what you stored, and keep the newest.

When the order matters to you, read the object again with `GET /bookings/{id}` or `GET /payments/{id}` before you act. That needs a key as well as the secret.

## When an address is switched off

An address that has failed every attempt for 3 days is switched off. The 3 days count from the first failure since the last delivered message, and any 2xx resets them. Once it is off:

- No new messages are made for it, and the ones still waiting are dropped.
- The admin shows "Not answering since" and the date of that first failure.
- Switching it on again in the admin starts a fresh count. It does not send what was dropped.

A shop that leaves the Premium plan sends nothing either. Messages still waiting are dropped. The addresses stay and send again once the shop is on Premium.

## Rules for an address

WeerOm checks the address when the shop adds it, and again before every attempt. An address that fails a check is refused, or its attempt fails.

- It starts with `https://`. The certificate must be valid for the hostname. A self-signed certificate fails.
- No user name or password in it, and at most 500 characters.
- The port is 443, 80 or one above 1023.
- The hostname resolves, and every address it resolves to is on the public internet. Private and local ranges are refused, such as `10.0.0.0/8`, `127.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` and `169.254.0.0/16`. In IPv6, only global addresses pass.
- WeerOm connects to the exact address it checked, and sends your hostname in the `Host` header and the TLS handshake.

To test on your own computer, put a tunnel with a public HTTPS address in front of it.

## The test message

**Send a test** in the admin posts one message to that address and waits for the answer:

```json
{
  "created_at": "2026-11-22T09:00:00.000Z",
  "data": { "object": { "object": "test" } },
  "id": "evt_c4e6a8b0d2f41a3c5e7b9d1f3a5c7e9b",
  "type": "test"
}
```

It carries `WeerOm-Event: test` and a signature like any other message. It is sent once, without retries, also to an address that is switched off. A failed test does not count toward switching the address off. Answer it with 2xx like the rest, and ignore its content.

## Polling as the fallback

Webhooks and the API work together. Each fits a different job:

| Use | When |
| --- | --- |
| Webhooks | You need to act within seconds of a change: an invoice per payment, a calendar that follows the agenda, a message in the staff chat. |
| Polling with `updated_after` or `paid_after` | A run once an hour or once a night is enough, such as a sheet or a newsletter list. Or nobody can add an address: a script on a laptop, a tool without a public HTTPS address. |
| Both | You cannot lose a change. Act on each webhook, and run a sync every few hours that reads what changed since its last run. It catches messages lost while your server was down for more than 33 hours. |

[Pagination](https://developers.weerom.com/docs/pagination#sync-only-what-changed) has the polling loop.

## Limits

- No API endpoint adds, lists or removes an address. The shop does that in the admin.
- The message does not name the shop. Software that serves several shops gives each one its own address, such as `https://example.com/weerom/noord`, and checks each message with that shop's secret.
- No event for customers, services or staff. Poll `GET /customers?updated_after=...` for customers.
- No replay. A message that failed all 7 attempts is gone. The API still holds the current state.
- The message holds the object as it was when the change happened, not what changed. Compare it with your own copy to see that.


# Get the shop

Source: https://developers.weerom.com/docs/reference/shop/getShop

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

The shop the key belongs to. A good first call: it proves the key works and names the currency and time zone of everything else.

**Keys:** every kind of key works here.

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `country` | string | ISO 3166-1 alpha-2. |
| `currency` | string | ISO 4217 code of every amount on this object. |
| `locale` | `en`, `nl`, `pt`, `fr`, `de` | The shop's own language. |
| `name` | string | The shop's name as customers see it. |
| `object` | `shop` |  |
| `time_zone` | string | IANA zone the shop's opening hours are in. |
| `url` | string | The shop's public site. |

Example:

```json
{
  "country": "BE",
  "currency": "EUR",
  "locale": "nl",
  "name": "Studio Noord",
  "object": "shop",
  "time_zone": "Europe/Brussels",
  "url": "https://studionoord.weerom.be"
}
```

### 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

Every kind of key: read key, write key and public key.

## What it does

- Every other time in the API is UTC. Use `time_zone` to show a time as the shop's clock reads it.
- `currency` follows the shop's country, and every amount the shop answers is in it.


# List services

Source: https://developers.weerom.com/docs/reference/services/listServices

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

Every service, in the order the shop shows them.

**Keys:** every kind of key works here.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | query | boolean | no | Only active ones, or only inactive ones. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].active` | boolean | False once the shop stopped offering it. |
| `data[].created_at` | string (date-time) | When the service was added. |
| `data[].currency` | string | ISO 4217 code of every amount on this object. |
| `data[].id` | string (uuid) | The service's id. |
| `data[].minutes` | integer | How long it takes. |
| `data[].name` | string | The name in the shop's own language. |
| `data[].name_translations` | object | The name in each language. An empty string means not translated. |
| `data[].name_translations.de` | string |  |
| `data[].name_translations.en` | string |  |
| `data[].name_translations.fr` | string |  |
| `data[].name_translations.nl` | string |  |
| `data[].name_translations.pt` | string |  |
| `data[].object` | `service` |  |
| `data[].price_cents` | integer | The list price, VAT included. |
| `data[].updated_at` | string (date-time) | When the service 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": [
    {
      "active": true,
      "created_at": "2026-03-02T08:15:00.000Z",
      "currency": "EUR",
      "id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
      "minutes": 45,
      "name": "Knippen en baard",
      "name_translations": {
        "de": "",
        "en": "Cut and beard",
        "fr": "Coupe et barbe",
        "nl": "Knippen en baard",
        "pt": ""
      },
      "object": "service",
      "price_cents": 4000,
      "updated_at": "2026-09-14T16:40:00.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

Every kind of key: read key, write key and public key.

## Sort

In the order the shop shows its services, then by `id`. The order is fixed.

## Filters

- `active=true` keeps the services the shop offers. `active=false` keeps the ones it stopped offering. Leave it out for both.

## What it does

- The whole list fits on one page: `has_more` is `false` and `next_cursor` is `null`. The list takes no `limit`, `cursor` or `order`, and sending one answers 400 `invalid_request`.


# Get a service

Source: https://developers.weerom.com/docs/reference/services/getService

```http
GET https://api.weerom.com/v1/services/{id}
```

One service by its id.

**Keys:** every kind of key works here.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The object's id. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `active` | boolean | False once the shop stopped offering it. |
| `created_at` | string (date-time) | When the service was added. |
| `currency` | string | ISO 4217 code of every amount on this object. |
| `id` | string (uuid) | The service's id. |
| `minutes` | integer | How long it takes. |
| `name` | string | The name in the shop's own language. |
| `name_translations` | object | The name in each language. An empty string means not translated. |
| `name_translations.de` | string |  |
| `name_translations.en` | string |  |
| `name_translations.fr` | string |  |
| `name_translations.nl` | string |  |
| `name_translations.pt` | string |  |
| `object` | `service` |  |
| `price_cents` | integer | The list price, VAT included. |
| `updated_at` | string (date-time) | When the service last changed. |

Example:

```json
{
  "active": true,
  "created_at": "2026-03-02T08:15:00.000Z",
  "currency": "EUR",
  "id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
  "minutes": 45,
  "name": "Knippen en baard",
  "name_translations": {
    "de": "",
    "en": "Cut and beard",
    "fr": "Coupe et barbe",
    "nl": "Knippen en baard",
    "pt": ""
  },
  "object": "service",
  "price_cents": 4000,
  "updated_at": "2026-09-14T16:40:00.000Z"
}
```

### 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.

### 404

No object with this id in the key's shop.

### 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

Every kind of key: read key, write key and public key.

## What it does

- An inactive service still answers, with `active: false`.
- `name` is the name in the shop's own language, or the English name when that one is empty.

## 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 |
| --- | --- | --- | --- |
| 404 | `not_found` | No object has this id, or the id is not a UUID. | Check the id. Ids are UUIDs from a list or from an earlier answer. |


# List staff

Source: https://developers.weerom.com/docs/reference/staff/listStaff

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

Everyone customers can book with, in the shop's order.

**Keys:** every kind of key works here.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | query | boolean | no | Only active ones, or only inactive ones. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].active` | boolean | False once they left the agenda. |
| `data[].created_at` | string (date-time) | When they were added. |
| `data[].id` | string (uuid) | The staff member's id. |
| `data[].name` | string | The name customers see when they book. |
| `data[].object` | `staff` |  |
| `data[].service_ids` | array of string (uuid) | The services this person does. |
| `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": [
    {
      "active": true,
      "created_at": "2026-03-02T08:15:00.000Z",
      "id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
      "name": "Sam",
      "object": "staff",
      "service_ids": [
        "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68"
      ],
      "updated_at": "2026-03-02T08:15:00.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

Every kind of key: read key, write key and public key.

## Sort

In the order the shop shows its staff, then by `id`. The order is fixed.

## Filters

- `active=true` keeps the people customers can book. `active=false` keeps the ones who left the agenda. Leave it out for both.

## What it does

- The whole list fits on one page: `has_more` is `false` and `next_cursor` is `null`. The list takes no `limit`, `cursor` or `order`, and sending one answers 400 `invalid_request`.
- `service_ids` is sorted by id, not in the shop's order of services.


# Get a staff member

Source: https://developers.weerom.com/docs/reference/staff/getStaffMember

```http
GET https://api.weerom.com/v1/staff/{id}
```

One staff member by their id.

**Keys:** every kind of key works here.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The object's id. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `active` | boolean | False once they left the agenda. |
| `created_at` | string (date-time) | When they were added. |
| `id` | string (uuid) | The staff member's id. |
| `name` | string | The name customers see when they book. |
| `object` | `staff` |  |
| `service_ids` | array of string (uuid) | The services this person does. |
| `updated_at` | string (date-time) | When the record last changed. |

Example:

```json
{
  "active": true,
  "created_at": "2026-03-02T08:15:00.000Z",
  "id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
  "name": "Sam",
  "object": "staff",
  "service_ids": [
    "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68"
  ],
  "updated_at": "2026-03-02T08:15:00.000Z"
}
```

### 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.

### 404

No object with this id in the key's shop.

### 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

Every kind of key: read key, write key and public key.

## What it does

- Someone who left the agenda still answers, with `active: false`.

## 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 |
| --- | --- | --- | --- |
| 404 | `not_found` | No object has this id, or the id is not a UUID. | Check the id. Ids are UUIDs from a list or from an earlier answer. |


# List free times

Source: https://developers.weerom.com/docs/reference/availability/listAvailability

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

The times a customer can book a service, for one day or up to 14 in a row. Leave `staff_id` out to get the free times of everyone who does the service. A slot is free now and may be gone a moment later: booking it answers 409 `slot_taken` when someone was faster.

**Keys:** every kind of key works here.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `date` | query | string | yes | The first day, as the shop's own calendar has it: 2026-11-30. At most 10 characters. |
| `days` | query | integer | no | How many days from `date` on. 1 to 14, default `1`. |
| `service_id` | query | string (uuid) | yes | The service to book. |
| `staff_id` | query | string (uuid) | no | Only this staff member's free times. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].ends_at` | string (date-time) | When an appointment in this slot would end. |
| `data[].object` | `slot` |  |
| `data[].service_id` | string (uuid) | The service the slot is for. |
| `data[].staff_id` | string (uuid) | Who would do it. |
| `data[].starts_at` | string (date-time) | Send this as `starts_at` to book the slot. |
| `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": [
    {
      "ends_at": "2026-11-30T09:45:00.000Z",
      "object": "slot",
      "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
      "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
      "starts_at": "2026-11-30T09:00:00.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

Every kind of key: read key, write key and public key.

## Sort

By `starts_at`, earliest first, then by `staff_id`. The order is fixed.

## Filters

- `date` is a day on the shop's own calendar, not a UTC day. With `days`, the list covers that day and the days after it, `days` in all.
- `staff_id` keeps one person's times. A staff member who is inactive, unknown or does not do the service gives an empty list, not an error.

## What it does

- The times are the ones the shop's own booking form offers: its opening hours, each person's hours and breaks, bookings already made, and the lead time. Times that have passed are left out.
- Without `staff_id`, the list holds the times of every active staff member who does the service. One time can show up once per person.
- The whole list fits on one page: `has_more` is `false` and `next_cursor` is `null`. The list takes no `limit`, `cursor` or `order`, and sending one answers 400 `invalid_request`.

## 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` | `date` is not a day, `days` is out of range, or `service_id` is missing. | Send `date` as a day such as `2026-11-30` and `days` from 1 to 14. |
| 404 | `not_found` | The service does not exist or is inactive. | Read `GET /services` and pick an active service. |


# 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. |


# Get a customer

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

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

One customer by their id.

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The object's id. |

## Responses

### 200

The request worked.

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

Example:

```json
{
  "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"
}
```

### 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.

### 404

No object with this id in the key's shop.

### 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`.

## 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 |
| --- | --- | --- | --- |
| 404 | `not_found` | No object has this id, or the id is not a UUID. | Check the id. Ids are UUIDs from a list or from an earlier answer. |


# Change a customer

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

```http
PATCH https://api.weerom.com/v1/customers/{id}
```

Changes a customer's name or blocks them. Send only the fields to change. There is no endpoint that makes a customer: making a booking makes its customer.

**Keys:** a key that may read and change. Any other key gets 403.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The object's id. |
| `Idempotency-Key` | header | string | no | Any unique text, such as a UUID. A retry with the same key and the same request gets the first answer back and changes nothing twice. Kept for 24 hours. At most 255 characters. |

## Request body

JSON, with `Content-Type: application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `blocked` | boolean | no | True stops online bookings from this customer. Bookings they have stay. |
| `name` | string | no | At least 1 characters, at most 120 characters. |

Example:

```json
{
  "blocked": true
}
```

## Responses

### 200

The request worked.

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

Example:

```json
{
  "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"
}
```

### 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.

### 404

No object with this id in the key's shop.

### 409

The time is taken, the booking is closed or past its cut-off, or the Idempotency-Key was used for another request.

### 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 write key. A read key or a public key answers 403 `key_not_allowed`.

## What it does

- Send `name`, `blocked` or both. A `name` is trimmed, and a name that is empty after trimming is ignored.
- `blocked: true` stops online bookings from the customer. Bookings they already hold stay. `blocked: false` lets them book again.
- A customer change sends no webhook. Read changes with `GET /customers?updated_after=...`.

## 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` | The body holds nothing to change, or a field is malformed. | Send `name`, `blocked` or both. `param` is `body` when the request held neither. |
| 404 | `not_found` | No object has this id, or the id is not a UUID. | Check the id. Ids are UUIDs from a list or from an earlier answer. |
| 409 | `idempotency_mismatch` | The `Idempotency-Key` was used before for a request with another method, path or body. | Make a new `Idempotency-Key` for a new request. |
| 409 | `request_in_progress` | The first request with this `Idempotency-Key` still runs. | Wait a second and send the same request with the same key again. |


# 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. |


# Make a booking

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

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

Books a free time for a customer and answers with the booking. The shop's rules apply as on its own booking form: opening hours, how far ahead a booking may be made, a paused form, a blocked customer. The customer gets the shop's confirmation mail and staff get their usual notice.

A public key books as a visitor, with a visitor's limits per address and per person, and may not send `as`. A write key may send `as: staff` to book like staff typing a walk-in into the agenda, which skips the lead time and the paused form.

Send an `Idempotency-Key` so a retry after a timeout cannot book twice.

**Keys:** a public key, or a key that may read and change. A key that may only read gets 403.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Any unique text, such as a UUID. A retry with the same key and the same request gets the first answer back and changes nothing twice. Kept for 24 hours. At most 255 characters. |

## Request body

JSON, with `Content-Type: application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `as` | `customer`, `staff` | no | `customer` keeps the shop's rules, such as how late a booking may still be cancelled. `staff` acts as the shop and skips them. Default `customer`. |
| `comments` | string | no | A note from the customer to the shop. At most 500 characters. |
| `customer` | object | yes | Who the booking is for. A customer the shop already knows by this phone is reused, else one is made. |
| `customer.email` | string | no | Where the confirmation and the reminder go. Needed when booking as a customer. As staff it may be left out, and then no mail goes out. At most 254 characters. |
| `customer.name` | string | yes | At least 1 characters, at most 120 characters. |
| `customer.phone` | string | yes | With the country code, such as +32470123456. A number without one is read as a number in the shop's country. At least 5 characters, at most 32 characters. |
| `locale` | `en`, `nl`, `pt`, `fr`, `de` | no | The language of the customer's mail. The shop's own when left out. |
| `remind_by_email` | boolean | no | Whether the customer gets the reminder mail. Default `true`. |
| `service_id` | string (uuid) | yes |  |
| `staff_id` | string (uuid) | yes | Who the booking is with. Take it from a slot. |
| `starts_at` | string (date-time) | yes | A `starts_at` from `GET /availability`. |

Example:

```json
{
  "customer": {
    "email": "lotte@example.com",
    "name": "Lotte Peeters",
    "phone": "+32470123456"
  },
  "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
  "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
  "starts_at": "2026-11-30T09:00:00.000Z"
}
```

## Responses

### 201

It was made.

| Field | Type | Description |
| --- | --- | --- |
| `cancel_reason` | string | Empty unless cancelled. |
| `cancelled_at` | string (date-time) or null | When it was cancelled. Null while it is not cancelled. |
| `code` | string | The short code the customer sees. |
| `comments` | string | What the customer wrote when booking. |
| `created_at` | string (date-time) | When the booking was made. |
| `currency` | string | ISO 4217 code of every amount on this object. |
| `customer` | object | Who the booking is for, as written on the booking when it was made. |
| `customer.email` | string or null |  |
| `customer.id` | string (uuid) or null | Null when the customer record was erased. |
| `customer.name` | string |  |
| `customer.phone` | string or null |  |
| `discount_percent` | integer | Percent off the list price. 0 without a deal. |
| `ends_at` | string (date-time) | When the appointment ends. |
| `id` | string (uuid) | The booking's id. |
| `list_price_cents` | integer | The price before any deal. |
| `locale` | string | The language the customer's mail about it goes out in. |
| `minutes` | integer | How long the appointment takes. |
| `object` | `booking` |  |
| `payment` | object or null | Set once staff noted a payment. Null until then. |
| `payment.amount_cents` | integer | What the customer paid for the service, VAT included. |
| `payment.method` | string or null | How they paid. Null when staff did not say. |
| `payment.paid_at` | string (date-time) | When staff noted the payment. |
| `payment.tip_cents` | integer |  |
| `price_cents` | integer | The price the customer was promised, VAT included. |
| `service` | object |  |
| `service.id` | string (uuid) or null | The service's id. Null when the shop deleted the service since. |
| `service.name` | string | The service's name when the booking was made. |
| `source` | `web`, `admin` | `web` for an online booking, `admin` for one staff typed in. |
| `staff_id` | string (uuid) | Who the booking is with. |
| `starts_at` | string (date-time) | When the appointment starts. |
| `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. |
| `updated_at` | string (date-time) | When the booking last changed. |

Example:

```json
{
  "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"
}
```

### 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.

### 409

The time is taken, the booking is closed or past its cut-off, or the Idempotency-Key was used for another request.

### 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 write key or a public key. A read key answers 403 `key_not_allowed`.

## What it does

- A customer the shop already knows by this phone number is reused. Otherwise the booking makes one. `customer.name` and `customer.email` on the booking are what you sent.
- The customer gets the shop's confirmation mail when you send an email. As `staff` without an email, no mail goes out.
- As `customer`, the shop's open-booking limit applies: a customer who already holds as many future confirmed bookings as the shop allows gets 429 `limit_reached`.
- As `staff`, the shop's lead time and a paused booking form do not apply, and a blocked customer can still be booked.
- The answer is 201 with the whole booking.

## Webhooks

A call that works sends `booking.created` to the shop's webhook addresses that listen for it. See [Webhooks](https://developers.weerom.com/docs/webhooks).

## 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 field is missing or malformed. As `customer`, a first and last name and an email are required. The staff member does not do this service. A public key sent `as`. | Fix the field `param` names, or show `message` to the customer. It holds the shop's own sentence, such as "First and last name are required". |
| 403 | `not_allowed` | As `customer`, the shop blocked this customer from booking online. | Do not retry. Send the customer to the shop. |
| 404 | `not_found` | The service or the staff member does not exist or is inactive. | Read `GET /services` and `GET /staff` again. Inactive ones cannot be booked. |
| 409 | `slot_taken` | The time is not one the shop offers, or someone booked it first. | Ask `GET /availability` again and let the customer pick another time. |
| 429 | `limit_reached` | A public key went over a visitor's limits per address, phone or email, or the customer holds as many open bookings as the shop allows. | Do not retry in a loop. Wait the seconds in `Retry-After` when the answer has it, or tell the customer to call the shop. |
| 503 | `bookings_paused` | As `customer`, the shop paused online booking. | Show the shop's phone number. A write key may book with `"as": "staff"`. |
| 409 | `idempotency_mismatch` | The `Idempotency-Key` was used before for a request with another method, path or body. | Make a new `Idempotency-Key` for a new request. |
| 409 | `request_in_progress` | The first request with this `Idempotency-Key` still runs. | Wait a second and send the same request with the same key again. |


# Get a booking

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

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

One booking by its id.

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The object's id. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `cancel_reason` | string | Empty unless cancelled. |
| `cancelled_at` | string (date-time) or null | When it was cancelled. Null while it is not cancelled. |
| `code` | string | The short code the customer sees. |
| `comments` | string | What the customer wrote when booking. |
| `created_at` | string (date-time) | When the booking was made. |
| `currency` | string | ISO 4217 code of every amount on this object. |
| `customer` | object | Who the booking is for, as written on the booking when it was made. |
| `customer.email` | string or null |  |
| `customer.id` | string (uuid) or null | Null when the customer record was erased. |
| `customer.name` | string |  |
| `customer.phone` | string or null |  |
| `discount_percent` | integer | Percent off the list price. 0 without a deal. |
| `ends_at` | string (date-time) | When the appointment ends. |
| `id` | string (uuid) | The booking's id. |
| `list_price_cents` | integer | The price before any deal. |
| `locale` | string | The language the customer's mail about it goes out in. |
| `minutes` | integer | How long the appointment takes. |
| `object` | `booking` |  |
| `payment` | object or null | Set once staff noted a payment. Null until then. |
| `payment.amount_cents` | integer | What the customer paid for the service, VAT included. |
| `payment.method` | string or null | How they paid. Null when staff did not say. |
| `payment.paid_at` | string (date-time) | When staff noted the payment. |
| `payment.tip_cents` | integer |  |
| `price_cents` | integer | The price the customer was promised, VAT included. |
| `service` | object |  |
| `service.id` | string (uuid) or null | The service's id. Null when the shop deleted the service since. |
| `service.name` | string | The service's name when the booking was made. |
| `source` | `web`, `admin` | `web` for an online booking, `admin` for one staff typed in. |
| `staff_id` | string (uuid) | Who the booking is with. |
| `starts_at` | string (date-time) | When the appointment starts. |
| `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. |
| `updated_at` | string (date-time) | When the booking last changed. |

Example:

```json
{
  "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"
}
```

### 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.

### 404

No object with this id in the key's shop.

### 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`.

## What it does

- Time staff blocked off is not a booking. Its id answers 404.

## When a field is null

- `cancelled_at` is `null` until the booking is cancelled.
- `payment` is `null` until staff note a payment for the booking.
- `payment.method` is `null` when no method was recorded with the 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 |
| --- | --- | --- | --- |
| 404 | `not_found` | No object has this id, or the id is not a UUID. | Check the id. Ids are UUIDs from a list or from an earlier answer. |


# Cancel a booking

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

```http
POST https://api.weerom.com/v1/bookings/{id}/cancel
```

Cancels a booking and frees its time. The customer gets the shop's cancellation mail. As `customer` the shop's cut-off applies: past it the answer is 409 `too_late`. A booking that is already cancelled or finished answers 409 `wrong_state`.

**Keys:** a key that may read and change. Any other key gets 403.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The object's id. |
| `Idempotency-Key` | header | string | no | Any unique text, such as a UUID. A retry with the same key and the same request gets the first answer back and changes nothing twice. Kept for 24 hours. At most 255 characters. |

## Request body

JSON, with `Content-Type: application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `as` | `customer`, `staff` | no | `customer` keeps the shop's rules, such as how late a booking may still be cancelled. `staff` acts as the shop and skips them. Default `customer`. |
| `reason` | string | no | Why, for the shop's own record. At most 300 characters. |

Example:

```json
{
  "reason": "Asked to come next week"
}
```

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `cancel_reason` | string | Empty unless cancelled. |
| `cancelled_at` | string (date-time) or null | When it was cancelled. Null while it is not cancelled. |
| `code` | string | The short code the customer sees. |
| `comments` | string | What the customer wrote when booking. |
| `created_at` | string (date-time) | When the booking was made. |
| `currency` | string | ISO 4217 code of every amount on this object. |
| `customer` | object | Who the booking is for, as written on the booking when it was made. |
| `customer.email` | string or null |  |
| `customer.id` | string (uuid) or null | Null when the customer record was erased. |
| `customer.name` | string |  |
| `customer.phone` | string or null |  |
| `discount_percent` | integer | Percent off the list price. 0 without a deal. |
| `ends_at` | string (date-time) | When the appointment ends. |
| `id` | string (uuid) | The booking's id. |
| `list_price_cents` | integer | The price before any deal. |
| `locale` | string | The language the customer's mail about it goes out in. |
| `minutes` | integer | How long the appointment takes. |
| `object` | `booking` |  |
| `payment` | object or null | Set once staff noted a payment. Null until then. |
| `payment.amount_cents` | integer | What the customer paid for the service, VAT included. |
| `payment.method` | string or null | How they paid. Null when staff did not say. |
| `payment.paid_at` | string (date-time) | When staff noted the payment. |
| `payment.tip_cents` | integer |  |
| `price_cents` | integer | The price the customer was promised, VAT included. |
| `service` | object |  |
| `service.id` | string (uuid) or null | The service's id. Null when the shop deleted the service since. |
| `service.name` | string | The service's name when the booking was made. |
| `source` | `web`, `admin` | `web` for an online booking, `admin` for one staff typed in. |
| `staff_id` | string (uuid) | Who the booking is with. |
| `starts_at` | string (date-time) | When the appointment starts. |
| `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. |
| `updated_at` | string (date-time) | When the booking last changed. |

Example:

```json
{
  "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"
}
```

### 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.

### 404

No object with this id in the key's shop.

### 409

The time is taken, the booking is closed or past its cut-off, or the Idempotency-Key was used for another request.

### 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 write key. A read key or a public key answers 403 `key_not_allowed`.

## What it does

- The booking's `status` becomes `cancelled`, `cancelled_at` is set and the time is free at once.
- The customer gets the shop's cancellation mail when the booking has an email. As `customer`, staff also get their usual notice. As `staff`, they do not.
- `reason` is stored as `cancel_reason`, trimmed.

## Webhooks

A call that works sends `booking.cancelled` to the shop's webhook addresses that listen for it. See [Webhooks](https://developers.weerom.com/docs/webhooks).

## 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 |
| --- | --- | --- | --- |
| 404 | `not_found` | No object has this id, or the id is not a UUID. | Check the id. Ids are UUIDs from a list or from an earlier answer. |
| 409 | `wrong_state` | The booking's `status` is not `confirmed`: it is cancelled, completed or a no-show. | Read the booking with `GET /bookings/{id}` and show its `status`. A cancelled booking stays cancelled. |
| 409 | `too_late` | As `customer`, the start is closer than the shop's cut-off for cancelling online. | Tell the customer to call the shop, or send `"as": "staff"` to act as the shop. |
| 409 | `idempotency_mismatch` | The `Idempotency-Key` was used before for a request with another method, path or body. | Make a new `Idempotency-Key` for a new request. |
| 409 | `request_in_progress` | The first request with this `Idempotency-Key` still runs. | Wait a second and send the same request with the same key again. |


# Move a booking

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

```http
POST https://api.weerom.com/v1/bookings/{id}/reschedule
```

Moves a booking to another time, and to another staff member when `staff_id` is sent. The customer gets the shop's mail about the move. As `customer` the shop's cut-off for moving applies.

**Keys:** a key that may read and change. Any other key gets 403.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The object's id. |
| `Idempotency-Key` | header | string | no | Any unique text, such as a UUID. A retry with the same key and the same request gets the first answer back and changes nothing twice. Kept for 24 hours. At most 255 characters. |

## Request body

JSON, with `Content-Type: application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `as` | `customer`, `staff` | no | `customer` keeps the shop's rules, such as how late a booking may still be cancelled. `staff` acts as the shop and skips them. Default `customer`. |
| `staff_id` | string (uuid) | no | Move it to this staff member as well. |
| `starts_at` | string (date-time) | yes | The new start, a `starts_at` from `GET /availability`. |

Example:

```json
{
  "starts_at": "2026-12-01T13:30:00.000Z"
}
```

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `cancel_reason` | string | Empty unless cancelled. |
| `cancelled_at` | string (date-time) or null | When it was cancelled. Null while it is not cancelled. |
| `code` | string | The short code the customer sees. |
| `comments` | string | What the customer wrote when booking. |
| `created_at` | string (date-time) | When the booking was made. |
| `currency` | string | ISO 4217 code of every amount on this object. |
| `customer` | object | Who the booking is for, as written on the booking when it was made. |
| `customer.email` | string or null |  |
| `customer.id` | string (uuid) or null | Null when the customer record was erased. |
| `customer.name` | string |  |
| `customer.phone` | string or null |  |
| `discount_percent` | integer | Percent off the list price. 0 without a deal. |
| `ends_at` | string (date-time) | When the appointment ends. |
| `id` | string (uuid) | The booking's id. |
| `list_price_cents` | integer | The price before any deal. |
| `locale` | string | The language the customer's mail about it goes out in. |
| `minutes` | integer | How long the appointment takes. |
| `object` | `booking` |  |
| `payment` | object or null | Set once staff noted a payment. Null until then. |
| `payment.amount_cents` | integer | What the customer paid for the service, VAT included. |
| `payment.method` | string or null | How they paid. Null when staff did not say. |
| `payment.paid_at` | string (date-time) | When staff noted the payment. |
| `payment.tip_cents` | integer |  |
| `price_cents` | integer | The price the customer was promised, VAT included. |
| `service` | object |  |
| `service.id` | string (uuid) or null | The service's id. Null when the shop deleted the service since. |
| `service.name` | string | The service's name when the booking was made. |
| `source` | `web`, `admin` | `web` for an online booking, `admin` for one staff typed in. |
| `staff_id` | string (uuid) | Who the booking is with. |
| `starts_at` | string (date-time) | When the appointment starts. |
| `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. |
| `updated_at` | string (date-time) | When the booking last changed. |

Example:

```json
{
  "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"
}
```

### 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.

### 404

No object with this id in the key's shop.

### 409

The time is taken, the booking is closed or past its cut-off, or the Idempotency-Key was used for another request.

### 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 write key. A read key or a public key answers 403 `key_not_allowed`.

## What it does

- The booking keeps its `id`, `code` and service. `starts_at` and `ends_at` move, and `staff_id` changes when you send it.
- The customer gets the shop's mail about the move when the booking has an email.

## Webhooks

A call that works sends `booking.updated` to the shop's webhook addresses that listen for it. See [Webhooks](https://developers.weerom.com/docs/webhooks).

## 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 field is malformed, or the new staff member does not do the booking's service. | Pick a staff member whose `service_ids` hold the booking's service. |
| 404 | `not_found` | No booking has this id, or no staff member has the `staff_id` you sent. | Check the booking id and the `staff_id`. |
| 409 | `wrong_state` | The booking's `status` is not `confirmed`, or it is not linked to a service. | Read the booking with `GET /bookings/{id}` and show its `status`. |
| 409 | `too_late` | As `customer`, the start is closer than the shop's cut-off for moving online. | Tell the customer to call the shop, or send `"as": "staff"` to act as the shop. |
| 409 | `slot_taken` | The new time is not one the shop offers, or someone booked it first. | Ask `GET /availability` for the booking's service again and pick another time. |
| 409 | `idempotency_mismatch` | The `Idempotency-Key` was used before for a request with another method, path or body. | Make a new `Idempotency-Key` for a new request. |
| 409 | `request_in_progress` | The first request with this `Idempotency-Key` still runs. | Wait a second and send the same request with the same key again. |


# List payments

Source: https://developers.weerom.com/docs/reference/payments/listPayments

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

Bookings a customer paid for, sorted by when staff noted the payment. This is the list an invoicing tool reads: each one carries the amount, the VAT inside it and who paid.

**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 `paid_at`, then the id. `desc` puts the payment noted last first. Default `desc`. |
| `method` | query | string | no | Only payments by this method, such as `cash`. At most 32 characters. |
| `paid_after` | query | string (date-time) | no | Only payments noted at or after this moment. ISO 8601 with an offset, such as 2026-11-01T00:00:00Z. |
| `paid_before` | query | string (date-time) | no | Only payments noted before 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[].amount_cents` | integer | What the customer paid for the service, VAT included. |
| `data[].booking_code` | string | The short code the customer sees on the booking. |
| `data[].booking_id` | string (uuid) | The booking this payment settled. |
| `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[].description` | string | The service's name, for an invoice line. |
| `data[].discount_percent` | integer | Percent off the list price from a deal. 0 without one. |
| `data[].id` | string (uuid) | The payment's id. The same value as `booking_id`. |
| `data[].list_price_cents` | integer | The price before any deal or change at the chair. |
| `data[].method` | string or null | How they paid. Null when staff did not say. |
| `data[].net_cents` | integer | `amount_cents` without VAT, rounded half up. |
| `data[].object` | `payment` |  |
| `data[].paid_at` | string (date-time) | When staff noted the payment. |
| `data[].service_id` | string (uuid) or null | The service's id. Null when the shop deleted the service since. |
| `data[].staff_id` | string (uuid) | Who did the work. |
| `data[].starts_at` | string (date-time) | When the appointment started. |
| `data[].tip_cents` | integer | Not part of `amount_cents`. |
| `data[].vat_cents` | integer | The VAT inside `amount_cents`. |
| `data[].vat_percent` | number | The shop's VAT rate on services as it is set today. 0 for a shop under an exemption. |
| `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": [
    {
      "amount_cents": 4000,
      "booking_code": "UEAMEFC9",
      "booking_id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
      "currency": "EUR",
      "customer": {
        "email": "lotte@example.com",
        "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
        "name": "Lotte Peeters",
        "phone": "+32470123456"
      },
      "description": "Knippen en baard",
      "discount_percent": 0,
      "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
      "list_price_cents": 4000,
      "method": "bancontact",
      "net_cents": 3306,
      "object": "payment",
      "paid_at": "2026-11-21T10:12:40.000Z",
      "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
      "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
      "starts_at": "2026-11-21T09:30:00.000Z",
      "tip_cents": 200,
      "vat_cents": 694,
      "vat_percent": 21
    }
  ],
  "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 `paid_at`, the moment staff noted the payment, then by `id`. `order=desc`, the default, lists the newest first. `order=asc` starts with the oldest, which is the order a sync wants.

## Filters

- `paid_after` includes a payment noted at that exact moment. A sync that sends the last `paid_at` it saw gets that payment again and skips it by `id`.
- `paid_before` leaves out a payment noted at that exact moment.
- `method` matches the stored word exactly, such as `cash` or `bancontact`.

## What it does

- A payment is a booking with a noted payment. Its `id` is the booking's id.
- When staff change the method or an amount, `paid_at` moves to that moment, so the payment comes back in a later `paid_after` run with the same `id`. When staff clear a payment, it leaves the list.
- `net_cents` and `vat_cents` use the shop's VAT rate as it is set at the moment you read.

## When a field is null

- `method` is `null` when no method was recorded with the 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, or the cursor is not one the API gave out. | Fix the parameter `param` names. |


# Get a payment

Source: https://developers.weerom.com/docs/reference/payments/getPayment

```http
GET https://api.weerom.com/v1/payments/{id}
```

One payment by its id, which is the id of the booking it settled. Answers 404 while the booking is unpaid.

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | The object's id. |

## Responses

### 200

The request worked.

| Field | Type | Description |
| --- | --- | --- |
| `amount_cents` | integer | What the customer paid for the service, VAT included. |
| `booking_code` | string | The short code the customer sees on the booking. |
| `booking_id` | string (uuid) | The booking this payment settled. |
| `currency` | string | ISO 4217 code of every amount on this object. |
| `customer` | object | Who the booking is for, as written on the booking when it was made. |
| `customer.email` | string or null |  |
| `customer.id` | string (uuid) or null | Null when the customer record was erased. |
| `customer.name` | string |  |
| `customer.phone` | string or null |  |
| `description` | string | The service's name, for an invoice line. |
| `discount_percent` | integer | Percent off the list price from a deal. 0 without one. |
| `id` | string (uuid) | The payment's id. The same value as `booking_id`. |
| `list_price_cents` | integer | The price before any deal or change at the chair. |
| `method` | string or null | How they paid. Null when staff did not say. |
| `net_cents` | integer | `amount_cents` without VAT, rounded half up. |
| `object` | `payment` |  |
| `paid_at` | string (date-time) | When staff noted the payment. |
| `service_id` | string (uuid) or null | The service's id. Null when the shop deleted the service since. |
| `staff_id` | string (uuid) | Who did the work. |
| `starts_at` | string (date-time) | When the appointment started. |
| `tip_cents` | integer | Not part of `amount_cents`. |
| `vat_cents` | integer | The VAT inside `amount_cents`. |
| `vat_percent` | number | The shop's VAT rate on services as it is set today. 0 for a shop under an exemption. |

Example:

```json
{
  "amount_cents": 4000,
  "booking_code": "UEAMEFC9",
  "booking_id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
  "currency": "EUR",
  "customer": {
    "email": "lotte@example.com",
    "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
    "name": "Lotte Peeters",
    "phone": "+32470123456"
  },
  "description": "Knippen en baard",
  "discount_percent": 0,
  "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
  "list_price_cents": 4000,
  "method": "bancontact",
  "net_cents": 3306,
  "object": "payment",
  "paid_at": "2026-11-21T10:12:40.000Z",
  "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
  "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
  "starts_at": "2026-11-21T09:30:00.000Z",
  "tip_cents": 200,
  "vat_cents": 694,
  "vat_percent": 21
}
```

### 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.

### 404

No object with this id in the key's shop.

### 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`.

## What it does

- A payment's id is the id of the booking it settled. A booking without a noted payment answers 404 here.
- `net_cents` and `vat_cents` are worked out on each read, at the shop's VAT rate as it is set at that moment.

## When a field is null

- `method` is `null` when no method was recorded with the 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 |
| --- | --- | --- | --- |
| 404 | `not_found` | No object has this id, or the id is not a UUID. | Check the id. Ids are UUIDs from a list or from an earlier answer. |
