Developers
The guest step
What your app shows the guest, how holds, confirms and releases work, how prices are set, and what happens when your app is slow or down.
The guest step is the part of the booking where your app speaks to the guest. After the guest has chosen a party size, a date and a time, BookingNinja asks your app what to show. Your app answers with blocks. BookingNinja draws them in the venue's own branding, so you write no front-end code.
How a booking flows through your step
- Step. The guest reaches your step. BookingNinja calls
POST /guest-step, thenPOST /availability, with the booking's slot. It keeps your reply for up to five minutes for the same booking and slot. - Hold. The guest chooses. BookingNinja calls
POST /holdswith their choices and answers. Your app holds what was chosen and replies with the price. - Pay. The price joins the booking total. The guest pays the venue.
- Confirm. When the booking is complete, BookingNinja calls
POST /holds/confirm. Your app turns the hold into a reservation. - Release. If the booking is cancelled, or the guest changes their mind, BookingNinja calls
POST /holds/release.
If the guest chooses nothing, or presses the skip button, BookingNinja does not call holds. If your app already holds something for that booking, BookingNinja releases it.
What every call carries
Every call has a context. These are the parts you will use most.
| Field | What it is |
|---|---|
context.installation_id |
The installation, ins_…. Use it to tell venues apart. |
context.venue |
The venue's opaque id, its name, timezone, currency (an ISO 4217 code) and locale |
context.settings |
The settings the venue saved, as venue and session objects. A setting the venue has not saved carries its manifest default. |
context.booking |
The booking: ref, status, session, date, start, end, party_size, and your hold_id and reservation_id once you have them |
context.channel |
Who is at the screen: guest or staff (see below) |
Ids are opaque. Your app never sees BookingNinja's own ids. The ven_… and ses_… ids are different for each app, so two apps cannot match up the same venue. Dates and times are the venue's own wall-clock time. All money is in the venue currency's minor units, so 300 is 3.00. The booking's ref is the same from the first draft to the end of the booking.
The reply to guest-step
{
"title": "Reserve a game",
"intro": "Pick up to two games and we will keep them for your table.",
"blocks": [
{
"type": "collection",
"id": "all_games",
"heading": "All games",
"layout": "grid",
"search": { "placeholder": "Search games" },
"card": { "subtitle": "{min_players} to {max_players} players", "badges": ["complexity"] }
},
{
"type": "fields",
"id": "extras",
"fields": [
{ "key": "teach", "type": "toggle", "label": "We would like someone to teach us the rules" }
]
}
],
"selection": { "min": 0, "max": 2, "max_quantity_per_item": 1 },
"skip_label": "No thanks"
}
titleis the step's heading. Without it BookingNinja uses the manifest'sdefault_label.blocksis what to show, top to bottom: from 1 to 30 blocks.selectionlimits the picks fromcollectionblocks, counted across the whole step: the fewest (min), the most different items (max), and the most of any one item (max_quantity_per_item). Options, plan and quantities blocks have limits of their own.skip_labelis the wording of the button that lets the guest carry on without choosing.
If your app has nothing to offer a booking, reply with skip set to true:
{ "skip": true }
The guest moves straight on and nothing is held. This is not a fault. Nothing counts against your app, and availability is not called. Use it for a party size or a date your app does not cover.
Block types
Five blocks collect something from the guest. The rest show information.
| Block type | What it is for |
|---|---|
collection |
A list of items to browse and choose from: games, rooms, add-ons. It has search, filters, sort and paging. |
fields |
A small form. Its answers arrive under each field's key. With per_guest it repeats once for each guest. |
options |
A short fixed list of choices: packages, room types, time slots. Up to 60 options, in five styles. |
quantities |
Rows the guest sets a number for: shoe sizes, hire kit, extras for each guest. Up to 40 rows. |
plan |
A picture of a layout with places to pick: lanes, pitches, desks. Up to 200 spots. Every spot is also a button, so the block works without the picture. |
notice |
A short message, in a neutral, info or warning tone |
text |
A heading or a paragraph |
hero |
A wide picture with a heading and a sentence, to open a step |
gallery |
Pictures to look at, as a carousel or a grid. Up to 12. |
steps |
An ordered list of what will happen |
details |
Facts as label and value pairs |
faq |
Questions that open to show their answers |
table |
A small table, such as a size chart. It can pick out one row. |
meter |
A bar showing how full something is |
links |
Links out to pages the app or venue hosts. They open in a new tab. |
divider |
A thin line and some space between groups of blocks |
The reference lists every field of every block, with an example of each.
A few rules apply to all of them:
- Ids share one namespace. A block's
idand thekeyof each field in afieldsblock must be unique across the whole step, because every answer is sent under its name in one flatanswersobject. BookingNinja keeps the first use of a name and drops later ones. An id matches[a-z][a-z0-9_]{0,39}. - Unknown block types are dropped, so a block type added later does not break your step on an older BookingNinja.
- Text is plain. BookingNinja strips markup from every string and cuts it to the length in the contract.
- Links and pictures must be HTTPS. A link or picture with any other address is dropped.
- A step that breaks the contract is skipped, as a whole.
The summary on the guest's confirmation uses a smaller set: details, steps, code and links, up to six blocks.
How answers reach holds
When the guest has chosen, BookingNinja sends the picks as items and everything else as answers.
{
"context": {
"installation_id": "ins_8f2k4a9b",
"venue": { "id": "ven_41c7d2", "name": "The Games Cafe", "timezone": "Europe/London", "currency": "GBP", "locale": "en-GB" },
"settings": { "venue": { "max_games": 2 }, "session": {} },
"channel": "guest",
"booking": {
"ref": "bkg_9d3f6e1a",
"status": "draft",
"session": { "id": "ses_5e8a1c", "name": "Saturday play" },
"date": "2026-12-05",
"start": "14:00",
"end": "16:00",
"party_size": 4
}
},
"items": [ { "id": "g_0042", "quantity": 1 } ],
"answers": {
"teach": true,
"package": "plus",
"shoes": { "size_7": 2, "size_9": 1 },
"guests": [ { "name": "Sam" }, {}, {}, {} ]
},
"replaces": null,
"expires_at": "2026-12-05T10:45:00Z"
}
itemsare the picks fromcollectionblocks, each with aquantity. The list is empty when the step has only other blocks.- A
fieldsblock contributes its field keys. A field hidden byvisible_whenis not sent. - A
fieldsblock withper_guestsends, under its block id, a list with exactly one object for each guest in the party. - An
optionsorplanblock sends, under its block id, the chosen id as text. Withmultipleit sends a list of ids, and never a list otherwise. - A
quantitiesblock sends an object of row id to quantity. Rows at zero are left out. With nothing chosen the object is empty. - A block the guest left unanswered is left out.
BookingNinja checks the answers against your blocks first, and refuses names your step does not define, so your app never receives them. Check them again anyway: only your app knows what it can honour.
Collections
A collection shows items. It works in one of two ways, set by its source.
Catalogue (catalogue, the default). BookingNinja keeps its own copy of your items, fetched from POST /catalogue. It searches, filters, sorts and pages that copy itself. This is fast, needs no call for each key press and keeps working while your app is slow. Settings and catalogue covers the sync. Search is always matched by BookingNinja on the copy.
Remote (remote). BookingNinja sends every change of search text, filter, sort or page to POST /collection and shows exactly what comes back, in your order. Use it for personalised or ranked results, catalogues too large or too changeable to sync, or live availability and prices. A remote collection needs no sync. If every collection in your app is remote, set catalogue.sync to false in the manifest and do not implement POST /catalogue.
A collection block names how the list looks:
{
"type": "collection",
"id": "all_games",
"heading": "All games",
"layout": "grid",
"source": "catalogue",
"item_ids": ["g_0001", "g_0042", "g_0077"],
"search": { "placeholder": "Search games", "min_length": 2 },
"filters": [
{ "id": "players", "label": "Players", "type": "fits_range", "min_key": "min_players", "max_key": "max_players", "default": 4 },
{ "id": "time", "label": "Play time", "type": "max", "key": "play_minutes", "choices": [30, 60, 90] }
],
"sort": [ { "label": "Name A to Z", "key": "name", "direction": "asc" } ],
"card": { "subtitle": "{min_players} to {max_players} players", "badges": ["complexity"] },
"page_size": 24
}
item_idsshows only those items, in that order. Leave it out to show the whole catalogue.card.subtitleis text with{attribute_key}placeholders. The attributes must be declared in the manifest'scatalogue.attributes.page_sizeis 24 by default and 48 at most.
Filters narrow a list. Each has a type:
| Filter type | What it does |
|---|---|
fits_range |
The chosen number lies between an item's min_key and max_key attributes, such as the fewest and most players |
max |
The item's attribute is at most the chosen number |
min |
The item's attribute is at least the chosen number |
one_of |
The item's attribute equals the chosen option |
any_of |
A tags attribute contains any chosen option |
toggle |
An on or off switch, sent as true or false. Remote collections only: only your app knows what it means. |
Remote collections
For a remote collection, BookingNinja sends:
{
"context": {
"installation_id": "ins_8f2k4a9b",
"venue": { "id": "ven_41c7d2", "name": "The Games Cafe", "timezone": "Europe/London", "currency": "GBP", "locale": "en-GB" },
"settings": { "venue": {}, "session": {} },
"channel": "guest",
"booking": {
"ref": "bkg_9d3f6e1a",
"status": "draft",
"session": { "id": "ses_5e8a1c", "name": "Saturday play" },
"date": "2026-12-05",
"start": "14:00",
"end": "16:00",
"party_size": 4
}
},
"collection_id": "all_games",
"query": "cat",
"filters": { "players": 4, "free_now": true },
"sort": { "key": "relevance", "direction": "desc" },
"cursor": null,
"limit": 24,
"selected": ["g_0042"]
}
Your reply is one page of items. It may also replace the collection's filters, sort options and heading, and add a notice:
{
"items": [
{
"id": "g_0007",
"name": "Catan",
"summary": "Trade, build and settle.",
"unavailable_label": "Reserved at 14:00",
"price_hint": "£3",
"badges": ["Staff pick"],
"rating": { "value": 4.5, "count": 128 }
}
],
"next_cursor": "c:24",
"total": 61,
"heading": "Results for \"cat\"",
"notice": "Showing games free at 14:00",
"valid_for_seconds": 15
}
An item can carry an unavailable_label to show it greyed out. next_cursor is your own opaque value: BookingNinja sends it back as cursor for the next page. An identical request is answered from a short cache for valid_for_seconds: 15 by default, 0 for never, and 300 at most.
If a remote call fails, the guest sees that the list could not load and can try again. The step is not skipped.
Availability
POST /availability asks which items are taken for the booking's slot, so BookingNinja can grey them out. It carries the same context as guest-step.
{
"unavailable": [
{ "id": "g_0007", "label": "Reserved" },
{ "id": "g_0042" }
]
}
An item you do not list is treated as free. BookingNinja uses up to 2,000 entries.
Your app must answer it, even when it has nothing to say. BookingNinja calls it after every guest-step, and if it fails, for any reason including a 404, your step is skipped. An app with only options, or only remote collections, replies {"unavailable": []}. A remote collection marks items unavailable in its own replies instead.
Holds
POST /holds runs when the guest chooses. Reserve what they chose until expires_at, and return the price.
{
"hold_id": "hld_4c1d9a",
"expires_at": "2026-12-05T10:45:00Z",
"lines": [
{ "item_id": "g_0042", "label": "Catan", "quantity": 1, "unit_price": 300 }
]
}
- One live hold for each booking. To extend or change a hold, BookingNinja never repeats the request. It sends a new one with
replacesset to the current hold's id, with the same items to extend. replacescan name a hold or a reservation. A replaced hold is released at once. A replaced reservation stays until the new hold is confirmed, and is then released. Count a superseded hold's or reservation's own items as free when you check availability.expires_atis the time (UTC) the hold must last until. BookingNinja sets it a little beyond the time the guest has to finish booking, so a hold never lapses before the draft does. Your reply'sexpires_atmust be no earlier than the one asked for, less two minutes. If it is earlier, BookingNinja does not accept the hold, because the guest would pay for something that may lapse.- Repeat calls. A repeat with the same
Idempotency-Keyis a retry. Return the first response.
If an item has gone, reply 409 with the code unavailable:
{
"error": {
"code": "unavailable",
"message": "Sorry, Catan has just been reserved for that time.",
"unavailable": ["g_0007"]
}
}
The message is shown to the guest. For any other 4xx reply, BookingNinja shows the message of the error too (300 characters at most), such as for 422 and invalid_request. A 5xx, a timeout or a reply that breaks the contract is a failure instead. With nothing held, the step is skipped and the guest books without it. If a hold already stands, it stays, and the guest is told their earlier choice still counts.
Confirm
POST /holds/confirm runs once the booking is complete. It carries the hold_id. Reply with a reservation_id of your own, and a guest_summary if you want the guest to see one.
{
"reservation_id": "res_77be1c",
"guest_summary": {
"heading": "Your games",
"lines": [ { "label": "Catan", "note": "Waiting for you at the front desk" } ],
"blocks": [
{ "type": "steps", "heading": "On the day", "items": [ { "title": "Say hello at the front desk" } ] }
]
}
}
The summary appears on the confirmation page and on the manage-booking page. Emails show the summary's lines, details, steps and the text of a code. They never show a QR code or a link.
Confirm must succeed while the hold is live, and a repeat must return the same reservation. If your app cannot be reached, BookingNinja tries again once a minute for 10 minutes. A refusal is final: BookingNinja records the failure on the booking, with what the guest was charged, for staff to follow up.
Release
POST /holds/release tells your app to let go of a hold or a reservation. Reply 200 with {}, even when it is already gone. BookingNinja sends it without holding the guest up. A hold your app is never told to release lapses at its expires_at.
{
"context": {
"installation_id": "ins_8f2k4a9b",
"venue": { "id": "ven_41c7d2", "name": "The Games Cafe", "timezone": "Europe/London", "currency": "GBP", "locale": "en-GB" },
"settings": { "venue": {}, "session": {} },
"booking": {
"ref": "bkg_9d3f6e1a",
"status": "cancelled",
"session": { "id": "ses_5e8a1c", "name": "Saturday play" },
"date": "2026-12-05",
"start": "14:00",
"end": "16:00",
"party_size": 4
}
},
"hold_id": null,
"reservation_id": "res_77be1c",
"reason": "cancelled"
}
The reason says why:
| Reason | What happened |
|---|---|
removed |
The guest skipped the step after choosing, or a staff action handed back a reservation the booking could no longer keep |
replaced |
The guest changed the party size, date or time before the booking was confirmed, so the hold no longer fits |
cancelled |
The booking was cancelled, including when it was cancelled while your app was still confirming it |
Pricing rules
Your app quotes the price. BookingNinja collects it.
- Your app sets the price, in
holds. Each line has alabel, aquantityand aunit_price. The line's total is the quantity times the unit price. An empty list adds nothing. Aprice_hinton an item, an option or the selection is only a label: the price charged is always the oneholdsreturns. - The money goes to the venue. BookingNinja makes no separate charge for your app. The lines join the booking total, and coupons, tax and the share due today treat them like add-ons. On the few venues that add tax on top of their prices, tax is added to your lines too, so the guest pays a little more than your app quoted.
- The price is fixed once the guest starts to pay. From the moment a payment starts, or the booking stops being a draft, nothing your app does changes the price. That includes an app that goes quiet when the guest returns to the step, a venue disconnecting your app or switching the step off, and a staff action. Only the guest choosing again does.
- A change after booking never changes the price. A guest can swap their choice from the manage-booking page. BookingNinja sends
holdswithreplacesset to the reservation, thenholds/confirm. A quote above what the booking has paid for is refused. A quote equal to it relabels the lines with the same total. A lower one leaves them as they are, with no refund. So a guest can add a choice after booking only when it is free, and remove one only when nothing was charged. - A staff-made add is not charged. Staff can add your step to a booking made in the admin, or one whose guest skipped the step. Your app is asked as usual, and the reservation is made, but the lines are never added to the price. Staff are told the amount, to take at the venue or to ask for with a payment request.
Who is at the screen
context.channel is guest when the guest is filling in the step, and staff when a member of the venue's staff adds your step to a booking from the admin. It is sent with guest-step and collection, and with availability and holds when a person is choosing. It is not sent when BookingNinja acts on its own, such as moving a reservation with the booking.
On the staff screen, only collection and fields blocks are drawn. An app that needs more for staff should return a simpler step when the channel is staff, or reply skip.
Several apps on one session
A session can have any number of apps with their step switched on. Guests see them one after another, in the order the venue sets in the session editor. Your app only ever sees its own calls, and nothing changes in the contract. A hold, a price and a summary belong to one app each.
Time limits, and when your app is slow or down
BookingNinja never leaves a guest stuck because an app is slow. It waits this long for each call, then gives up:
| Call | Seconds BookingNinja waits |
|---|---|
guest-step |
2 |
availability |
2 |
collection |
2 |
holds |
3 |
holds/confirm |
5 |
holds/release |
5 |
blocks |
3 |
actions |
5 |
settings/options |
5 |
settings/validate |
5 |
catalogue |
30 |
events |
10 |
- Guest step, availability and holds. If your app times out, fails, or answers outside the contract, the step is skipped and the guest books without it. The booking history records that the step was skipped.
- Remote collection. The guest sees that the list could not load, and can try again.
- Confirm. BookingNinja tries again, as above.
- Staff blocks. Staff see the last blocks your app sent.
- Events. BookingNinja tries again, as the staff and alerts guide describes.
- Reply size. A reply over 2 MB is refused. Every successful reply must be a JSON object, even when it has nothing to say: an empty body counts as a failure.
- Pausing. After 5 failed calls in a row, BookingNinja pauses your installation. It then makes one call every 60 seconds to see whether your app has recovered, and nothing else. A timeout, a connection failure or a
5xxreply counts as a failure. A4xxreply does not: your app is up, and it has refused.