Make a booking
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.
apiKeyAuthorizationBearer wo_live_...A key from the shop's admin. Secret keys start with wo_live_, public keys with wo_pub_.
Idempotency-Key?stringAny 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.
length <= 255application/json- body
as?stringcustomer keeps the shop's rules, such as how late a booking may still be cancelled. staff acts as the shop and skips them.
"customer""customer""staff"comments?stringA note from the customer to the shop.
length <= 500customer*Who the booking is for. A customer the shop already knows by this phone is reused, else one is made.
locale?stringThe language of the customer's mail. The shop's own when left out.
"en""nl""pt""fr""de"remind_by_email?booleanWhether the customer gets the reminder mail.
trueservice_id*stringuuidstaff_id*stringWho the booking is with. Take it from a slot.
uuidstarts_at*stringA starts_at from GET /availability.
date-timeIt was made.
application/json- response
An appointment.
cancel_reason*stringEmpty unless cancelled.
cancelled_at*|nullcode*stringThe short code the customer sees.
comments*stringWhat the customer wrote when booking.
created_at*stringWhen the booking was made.
date-timecurrency*stringISO 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*integerPercent off the list price. 0 without a deal.
ends_at*stringWhen the appointment ends.
date-timeid*stringThe booking's id.
uuidlist_price_cents*integerThe price before any deal.
locale*stringThe language the customer's mail about it goes out in.
minutes*integerHow long the appointment takes.
object*stringpayment*|nullprice_cents*integerThe price the customer was promised, VAT included.
service*source*stringweb for an online booking, admin for one staff typed in.
"web""admin"staff_id*stringWho the booking is with.
uuidstarts_at*stringWhen the appointment starts.
date-timestatus*stringconfirmed is booked and still to come or not yet closed by staff. completed is done. no_show means the customer did not come.
"confirmed""completed""cancelled""no_show"updated_at*stringWhen the booking last changed.
date-timecurl -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"}'{ "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.nameandcustomer.emailon the booking are what you sent. - The customer gets the shop's confirmation mail when you send an email. As
staffwithout 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 429limit_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.
| 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. |