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