Skip to Content
Developers

Build a 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:

StepRequest
Read the shop's time zoneGET /shop
Pick a serviceGET /services
Pick a staff member, if the shop lets customers chooseGET /staff
Show free timesGET /availability
BookPOST /bookings

Which key

Where the code runsKeyWhy
In the customer's browserA 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 pageA 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.

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.

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.

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

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

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

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);
{
  "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
}
ParameterWhat it does
service_idRequired. The service to book. An inactive or unknown service answers 404.
dateRequired. 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.
days1 to 14. How many days from date on. 1 when left out.
staff_idOnly 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:

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.

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,
  });
}
FieldNotes
customer.nameFirst and last name. A booking with one name answers 400 "First and last name are required".
customer.phoneWith 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.emailRequired for a booking made as a customer. The confirmation and the reminder go here.
commentsA note to the shop, up to 500 characters.
localeThe language of the customer's mail: en, nl, fr, de or pt. The shop's own when left out.
remind_by_emailfalse 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:

{
  "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.

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 has the rules.

Handle the answer

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.

StatuscodeWhenWhat the page does
201The booking is made.Show the code and the time.
400invalid_requestA 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.
403not_allowedThe shop blocked this customer from booking online.Ask them to call the shop.
404not_foundThe service or the staff member is gone or inactive.Load the services again.
409slot_takenThe 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.
429limit_reachedToo 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.
503bookings_pausedThe 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.

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 shows this setup.

On this page