SINGLE_SESSION item, funding exactly
one booking. This guide also assumes the BFF pattern
and an API key already set up.
How it works
A single booking is three calls, always in this order:- Create the order with one
SINGLE_SESSIONitem. This is what makes the session purchasable — it’s the order item the booking will draw down. - Read the order item’s id. The order-create response already includes it, but if the booking step runs later or in a different request, look it up again with the aggregate endpoint.
- Create the booking, with the service line carrying
businessModelType: "SINGLE_BOOKING"plus theorderIdandorderItemIdfrom steps 1–2.
Payment is not required. Credits exist the moment the order is created,
not when it’s paid. The order stays
DRAFT and the booking still succeeds —
don’t gate booking on Stripe. Layer payment on afterward with
Accept payments with Stripe.
A CANCELLED order books nothing: 409 ORDER_CANCELLED.POST /bookings books immediately — there’s no reservation window. To
reserve this supplier’s time while the client pays, hold it first:
POST /holds { intervals: [...] }, then convert the hold into this same
booking on payment success. A single session can be held on its own — no
package, no slate. Each held interval takes the same location fields as
the booking body below (bookingTz and locationType are required, and
locationType decides the rest) — the hold is what convert rebuilds the
booking from. See
Hold slots during checkout.If you do hold the time, you must convert it: this route will not consume
your hold and returns 409 SLOT_HELD naming the reservationId you
created.1
Create the order
Create an order with a single Booking on a client’s behalf with no client signed in? Take the The response nests the order under
SINGLE_SESSION item naming the service and
offering being booked. You don’t send a price — the server prices the item
from the offering itself. You do need to tell the order where this
session happens: this example books a TRAVEL_ZONE session (Step 3 below),
so it passes the client’s service address — the same one the booking call
uses. Booking a PHYSICAL session instead? Pass that Location’s
locationId here rather than address. See
Regional pricing for the full priority order
(reservationId → locationId → address) and why it matters.Resolve the client’s clientId on the server. Never trust a clientId the
browser sends: anyone can put another client’s id in a request body. For a
signed-in client, POST /clients/me with their token returns it (see
Onboard the client):clientId
from your own records on the server instead.order, not at the top level:2
Get the order item id
You already have Same shape as the create response —
orderItemId from the create response above — for a
single, immediate checkout you can skip straight to Step 3. If the booking
step happens later, or in a separate request that only has the orderId,
fetch it again with the aggregate endpoint:data.order plus data.items[]. Read
the SINGLE_SESSION item’s orderItemId off data.items[0].orderItemId.3
Create the booking
Create the booking. The service line carries A successful response returns the created booking,
businessModelType: "SINGLE_BOOKING" plus the orderId/orderItemId pair from steps 1–2 — this
is what ties the schedule entry back to the order item it draws down. The
example below uses locationType: "TRAVEL_ZONE", which needs the most
fields; see the location rules warning below for PHYSICAL and VIRTUAL.status: "SCHEDULED":The
bookingLocal* fields are computed server-side from bookingTz — never
send them yourself. Times are HH:mm:ss. See Timezones.The booking response doesn’t echo the service lines. Read them from
GET /bookings/{bookingId}/aggregate.Reference
Endpoints used in this guide
Configuration
Errors and edge cases
See Errors for the full envelope and code list.