Skip to Content
Developers
Bookings

Make a booking

POST
/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.

Authorization

apiKey
headerAuthorizationBearer wo_live_...

A key from the shop's admin. Secret keys start with wo_live_, public keys with wo_pub_.

Header parameters

Idempotency-Key?string

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.

Lengthlength <= 255

Request body

application/json
  1. body
as?string

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"
Value in"customer""staff"
comments?string

A note from the customer to the shop.

Lengthlength <= 500
customer*

Who the booking is for. A customer the shop already knows by this phone is reused, else one is made.

locale?string

The language of the customer's mail. The shop's own when left out.

Value in"en""nl""pt""fr""de"
remind_by_email?boolean

Whether the customer gets the reminder mail.

Defaulttrue
service_id*string
Formatuuid
staff_id*string

Who the booking is with. Take it from a slot.

Formatuuid
starts_at*string

A starts_at from GET /availability.

Formatdate-time

Response body

It was made.

application/json
  1. response

An appointment.

cancel_reason*string

Empty unless cancelled.

cancelled_at*|null
code*string

The short code the customer sees.

comments*string

What the customer wrote when booking.

created_at*string

When the booking was made.

Formatdate-time
currency*string

ISO 4217 code of every amount on this object.

customer*

Who the booking is for, as written on the booking when it was made.

discount_percent*integer

Percent off the list price. 0 without a deal.

ends_at*string

When the appointment ends.

Formatdate-time
id*string

The booking's id.

Formatuuid
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*string
payment*|null
price_cents*integer

The price the customer was promised, VAT included.

service*
source*string

web for an online booking, admin for one staff typed in.

Value in"web""admin"
staff_id*string

Who the booking is with.

Formatuuid
starts_at*string

When the appointment starts.

Formatdate-time
status*string

confirmed is booked and still to come or not yet closed by staff. completed is done. no_show means the customer did not come.

Value in"confirmed""completed""cancelled""no_show"
updated_at*string

When the booking last changed.

Formatdate-time
Example request
curl -X POST 'https://api.weerom.com/v1/bookings' \  -H 'Content-Type: application/json' \  -d '{  "customer": {    "email": "[email protected]",    "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"}'
Example response
{  "cancel_reason": "",  "cancelled_at": null,  "code": "UEAMEFC9",  "comments": "",  "created_at": "2026-11-18T14:02:11.000Z",  "currency": "EUR",  "customer": {    "email": "[email protected]",    "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"}

Details

Keys

Write keyPublic key

Any other kind of 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.

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. Errors has all of them.

StatuscodeWhenWhat to do
400invalid_requestA 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".
403not_allowedAs customer, the shop blocked this customer from booking online.Do not retry. Send the customer to the shop.
404not_foundThe service or the staff member does not exist or is inactive.Read GET /services and GET /staff again. Inactive ones cannot be booked.
409slot_takenThe time is not one the shop offers, or someone booked it first.Ask GET /availability again and let the customer pick another time.
429limit_reachedA 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.
503bookings_pausedAs customer, the shop paused online booking.Show the shop's phone number. A write key may book with "as": "staff".
409idempotency_mismatchThe Idempotency-Key was used before for a request with another method, path or body.Make a new Idempotency-Key for a new request.
409request_in_progressThe first request with this Idempotency-Key still runs.Wait a second and send the same request with the same key again.