Behio Storefront SDK
Catalog & Products

Bookings

Online appointments for services (salon, clinic, lessons) as a ready widget or through the SDK, with free times, a change and cancel link and rate limits

Bookings is a module of the Behio admin: the owner sets up services (length, price), staff, opening hours and branches, and customers book a free time online. There are two ways to put it on a website:

  • The widget: two lines of HTML, works on any website (WordPress, Wix, a Behio Themes site, your own code). Behio hosts the whole flow, including the confirmation and the change and cancel page.
  • The SDK: your own UI on top of client.bookings.*, for a storefront built with @behio/storefront-sdk.

Booking endpoints work with both e-shop keys and website keys. The Bookings module must be on in the admin, otherwise every call answers 404 be.bookings.widgetNotFound. Available since SDK 2.24.0.

The widget (any website)

Copy the embed code from the admin (Bookings, Settings). It looks like this:

<div data-behio-booking="YOUR_PUBLIC_KEY" data-lang="cs"></div>
<script async src="https://app.behio.com/booking-widget.js"></script>

The script finds every [data-behio-booking] element and puts the booking flow into it as an iframe that grows with its content (no inner scrollbar). The public key is not a secret: it identifies the business, nothing more.

AttributeValuesDefault
data-behio-bookingpublic key of the booking widgetrequired
data-langcs, sk, encs
data-themelight, dark, auto (follows the visitor's system)light
data-behio-booking-buttonpresent = a button that opens the flow in a window over the page; the element's text is the button labelinline frame
<!-- A button instead of the inline frame -->
<div data-behio-booking="YOUR_PUBLIC_KEY" data-lang="en" data-behio-booking-button>Book a visit</div>
<script async src="https://app.behio.com/booking-widget.js"></script>

Style the button with the behio-booking-button class. The window closes with the cross, a click outside or Escape.

Without JavaScript you can link straight to the hosted page https://app.behio.com/{lang}/book/{publicKey} or put ?embed=1 on it into your own iframe.

Allowed websites. When the owner lists allowed domains in the admin, the booking API answers 403 be.bookings.originNotAllowed to browser calls from any other origin. The hosted widget page always calls the API from Behio's own origin.

The SDK

Read the setup

const { data: config, error } = await client.bookings.getConfig();
if (error) throw new Error(error.message);

if (config.onlinePaused) {
  // Online booking is paused (plan limit). Show config.contactPhone / contactEmail instead of the flow.
}
// config.services: [{ id, categoryId, name, description, durationMinutes: 45, price: 450, currency: 'CZK' }]
// config.staff:    [{ id, name, title, bio, color, serviceIds }]
// config.timezone: 'Europe/Prague'

client.bookings.getConfig(): Promise<SdkResult<BookingConfig>>

  • price: null means price on site. Show it like that, never as 0.
  • Offer a staff step only when config.allowStaffChoice is true and more than one person does all the selected services (staff.serviceIds). Otherwise send staffId: null (anyone free).
  • maxAdvanceDays is how far ahead a customer may book; customerCancelHours is how long before the start the customer may still change or cancel.

Free times

const { data: free } = await client.bookings.getSlots({
  serviceIds: ['01SERVICE...', '01SERVICE...'], // in the order they follow each other
  staffId: null,                                 // or a person id
  from: '2026-10-21',
  to: '2026-11-03',                              // at most 31 days per call
});
// free.slots: [{ startMs: 1792587600000, endMs: 1792591500000 }, ...]
// free.durationMinutes: 65

client.bookings.getSlots(query: BookingSlotsQuery): Promise<SdkResult<BookingSlots>>

Time zone. from and to are days in the branch time zone (config.timezone), not the visitor's. Show every day and time in that zone too, and say so when it differs from the visitor's:

const time = new Intl.DateTimeFormat('cs-CZ', { hour: '2-digit', minute: '2-digit', timeZone: config.timezone });
time.format(new Date(slot.startMs)); // "10:00" in Prague, wherever the visitor is

Free times change with every booking, so fetch them when the customer picks the services, not ahead.

Create a booking

import { errorCode, errorMessage } from '@behio/storefront-sdk';

const { data, error } = await client.bookings.create({
  serviceIds,
  staffId: null,
  startMs: slot.startMs,
  name: 'Jana Nováková',
  email: '[email protected]',
  phone: '+420 777 123 456', // optional
  note: null,                // optional
  locale: 'cs',              // language of the confirmation email
  website: honeypotValue,    // hidden input, people leave it empty
});

if (errorCode(error) === 'be.bookings.slotTaken') {
  // 409: someone was faster. Reload the free times and let the customer pick again.
} else if (error) {
  showError(errorMessage(error, 'cs'));
} else {
  // data.booking.code: 'PAB5A1', data.booking.status: 'CONFIRMED' or 'PENDING'
  // data.manageToken: link the customer to your change and cancel page
}

client.bookings.create(input: BookingCreateInput): Promise<SdkResult<BookingCreated>>

  • status: 'PENDING' when the owner confirms bookings by hand (config.requireApproval). Say "waiting for confirmation", not "booked".
  • The confirmation email with the change and cancel link goes out automatically. manageToken is the same token; treat it like a password (no analytics, no logs).
  • Render the honeypot as a hidden <input name="website" tabindex="-1" autocomplete="off"> and send its value. A filled honeypot is rejected with be.bookings.rejected.

Change or cancel

The confirmation email links to the Behio page /{lang}/book/manage/{token}. If you build your own page instead:

const { data: booking, error } = await client.bookings.getByToken(token);
if (errorCode(error) === 'be.bookings.manageNotFound') return notFound();

if (booking.canChange) {
  // until booking.changeDeadline (ms)
  const { data: free } = await client.bookings.getManageSlots(token, { from, to });
  await client.bookings.reschedule(token, { startMs: free.slots[0].startMs });
  await client.bookings.cancel(token, { reason: 'I cannot make it' });
} else {
  // too late to change online: show booking.contactPhone
}
MethodSignature
getByToken(token: string) => Promise<SdkResult<Booking>>
getManageSlots(token: string, query: { from: string; to: string }) => Promise<SdkResult<BookingSlots>>
reschedule(token: string, input: { startMs: number }) => Promise<SdkResult<Booking>>
cancel(token: string, input?: { reason?: string | null }) => Promise<SdkResult<Booking>>

Errors and limits

CodeStatusWhat to do
be.bookings.slotTaken409The time is gone. Reload free times, keep the selected services.
be.bookings.onlineLimitReached403Online booking is paused for this month (plan limit). Show the phone or email from the config.
be.bookings.changeTooLate403Past the change deadline. Show booking.contactPhone.
be.bookings.manageNotFound404Unknown or old token. Ask the customer to use the latest email.
be.bookings.widgetNotFound404The module is off or the key is wrong.
be.bookings.staffCannotDoServices400The chosen person does not do every selected service.
be.bookings.tooManyRequests429Rate limit. Wait a minute.

Rate limits protect the business from spam: one visitor can create at most 5 bookings in 10 minutes and 20 a day, one business takes at most 120 online bookings an hour, and changes or cancellations are limited to 20 a minute. SDK calls also count toward the usual storefront rate limit of the site key (POST /bookings has its own bucket of 10 a minute). errorMessage(error, locale) turns these codes into a sentence for the customer in Czech, Slovak or English; for be.bookings.onlineLimitReached it gives a general sentence on purpose, so show your own with the contact from the config.

React hooks

import { useBookingConfig, useBookingSlots, useCreateBooking } from '@behio/storefront-sdk/react';

const { data: config } = useBookingConfig();
const { data: free, isFetching } = useBookingSlots({ serviceIds, staffId, from, to });
const create = useCreateBooking(); // refreshes free times after every attempt
await create.mutateAsync({ serviceIds, startMs, name, email, website: '' });

For the change and cancel page: useManagedBooking(token), useManagedBookingSlots(token, { from, to }), useCancelBooking(token), useRescheduleBooking(token).

Read the setup server-side for the first render (client.bookings.getConfig()); free times are the customer's choice, so loading them in the browser with a visible spinner is right.

On this page