Skip to main content
This guide walks through the single-session booking flow end to end: create an order, read the order item it produced, then create the booking that consumes it. For a client checkout that also holds the time and takes payment, start from Client checkout, end to end. It builds on The booking engine model — read that first if you haven’t. The one rule to keep in mind here: you can’t create a booking without an order item to draw down. For a single session, that means one order with one 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:
  1. Create the order with one SINGLE_SESSION item. This is what makes the session purchasable — it’s the order item the booking will draw down.
  2. 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.
  3. Create the booking, with the service line carrying businessModelType: "SINGLE_BOOKING" plus the orderId and orderItemId from 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 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):
Booking on a client’s behalf with no client signed in? Take the clientId from your own records on the server instead.
Without reservationId, locationId, or address, the order prices off the client’s default saved address (or their first saved address, if no default is set). Only a client with no saved address at all prices at the offering’s DEFAULT rule. Either way, the price and currency may differ from the regional price you displayed. If you get Item currency X does not match order currency Y, that’s what happened: you told the order what currency you quoted, but not where the session happens, so it resolved a different regional rule. See Regional pricing.
The response nests the order under order, not at the top level:
The order id is at data.order.orderId, not data.orderId. This trips up naive res.data.orderId unwrapping — every order response is shaped { order, items, summary }.
2

Get the order item id

You already have 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:
Same shape as the create response — 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 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.
A successful response returns the created booking, 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.
Location fields depend on locationType — the API rejects the wrong combination with a 400:The address object (addressOneLine, streetNumber, streetName, city, state, country as ISO-2, zipCode, plus optional unitNumber) is required on every TRAVEL_ZONE booking — there’s no fallback that derives it for you on the single-booking path.

Reference

Endpoints used in this guide

Configuration

Errors and edge cases

See Errors for the full envelope and code list.