Check out bookings from another till

What it is

The checkout hand-off is one address with two calls: GET and POST /api/v1/{slug}/appointments/{id}/checkout. GET returns what the booking comes to: each service and extra with its lineId and who did it, the price, discounts, tax lines, the deposit already paid, and dueCents, which is exactly what to take. POST records the sale your till took, completes the booking and links the sale to it, using the same checkout code as Bookatu's own till.

Why it helps

Nobody rings up a visit twice, and the booking, the sale, staff credit and the money line up in Bookatu as if its own till had taken it. Posting is idempotent on your externalSaleId, so a retry after a dropped connection returns replayed: true and writes nothing.

How to use it

1. 1Owners and admins make the key in Settings, then API & monitoring, under API keys. In What this key may do, tick both boxes on the Checkout at another till row: See what a booking comes to at checkout (checkout:read) and Check bookings out from another till (checkout:write). These are opt-in, and a key made before scopes never carries them. The maker must be able to see everyone's calendar (for checkout:read) and edit the calendar (for checkout:write). Add See bookings (bookings:read) to list the day's bookings with GET /appointments, and See clients (customers:read) if the till needs the client's name, email and phone. Without it the client comes by id only.
2. 2Send the key as Authorization: Bearer on every call. Call GET /api/v1/{slug}/appointments/{id}/checkout and ring up its lines. checkout.allowed says whether the booking can be checked out now, and checkout.blocked gives the reason: not_live, deposit_pending or already_checked_out.
3. 3Take the money, then POST to the same address with { externalSaleId, source, amountCents, currency, tender, tipCents, tipSplit, lines }. externalSaleId is your till's own sale id. source names the till, such as moneris_mgr (it defaults to external and can never be bookatu). amountCents must equal dueCents. currency is optional but must be the business's. tender is card, cash or other. lines, as [{ lineId, staffId }], credits a line to someone else.
4. 4Posting the same externalSaleId from the same till again returns the original sale with replayed: true. Refusals write nothing and give a reason: 409 amount_mismatch (with expectedCents), already_checked_out, external_sale_used, lines_changed (read the checkout again), not_live or deposit_pending; 422 currency or tip_split; 503 while the hand-off is still being switched on for the business.
5. 5To hear about every checkout, add a webhook in the Webhooks card on the same page and tick booking.checked_out under Only if you tick it. It is never sent to an endpoint that takes all events. It also fires for checkouts at Bookatu's own till (sale.source bookatu), with the same payload as GET and the client by id only.
6. 6The full reference, with every field and example, is on the developer docs at /developers#checkout-handoff, and as markdown at /developers.md.