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.
| Attribute | Values | Default |
|---|---|---|
data-behio-booking | public key of the booking widget | required |
data-lang | cs, sk, en | cs |
data-theme | light, dark, auto (follows the visitor's system) | light |
data-behio-booking-button | present = a button that opens the flow in a window over the page; the element's text is the button label | inline 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: nullmeans price on site. Show it like that, never as 0.- Offer a staff step only when
config.allowStaffChoiceis true and more than one person does all the selected services (staff.serviceIds). Otherwise sendstaffId: null(anyone free). maxAdvanceDaysis how far ahead a customer may book;customerCancelHoursis 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: 65client.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 isFree 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.
manageTokenis 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 withbe.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
}| Method | Signature |
|---|---|
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
| Code | Status | What to do |
|---|---|---|
be.bookings.slotTaken | 409 | The time is gone. Reload free times, keep the selected services. |
be.bookings.onlineLimitReached | 403 | Online booking is paused for this month (plan limit). Show the phone or email from the config. |
be.bookings.changeTooLate | 403 | Past the change deadline. Show booking.contactPhone. |
be.bookings.manageNotFound | 404 | Unknown or old token. Ask the customer to use the latest email. |
be.bookings.widgetNotFound | 404 | The module is off or the key is wrong. |
be.bookings.staffCannotDoServices | 400 | The chosen person does not do every selected service. |
be.bookings.tooManyRequests | 429 | Rate 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.