Developers

BookingNinja Apps: developer reference

What an app is, how a booking flows through it, how requests are signed, and every endpoint with its fields and an example. This page is generated from the contract's JSON Schema files.

What an app is

An app is an outside service that plugs into a venue's booking flow and admin over HTTP. BookingNinja draws every screen from JSON that your app returns, so you write no front-end code.

Your app is a web service with an HTTPS base URL. BookingNinja calls it at {base_url}/{path}, for example {base_url}/guest-step. Your app calls BookingNinja's API with a token. The base URL must be reachable from the public internet. BookingNinja refuses a host that resolves to a private address.

An app declares what it uses in its manifest: a step in the guest booking flow, blocks and buttons for staff on a booking, a framed panel, a summary on the guest's confirmation, events, and settings the venue fills in. Declare only the points your app uses.

An installation is your app connected to one venue. The ids your app sees are opaque: ins_… for the installation, ven_… for the venue, ses_… for a session, bkg_… for a booking and app_… for your app. BookingNinja's internal ids are never sent. Venue and session ids are different for each app, so two apps cannot match up the same venue.

Two ways to list items

A step can show a list of items, such as games to reserve. A list is a collection block, and it works in one of two ways. You choose with the block's source.

Synced catalogue (catalogue, the default). Your app implements POST /catalogue and BookingNinja keeps its own copy of the items. BookingNinja 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. BookingNinja matches the search box itself on that copy. If you want to do the text matching yourself, make the collection remote instead. Declare the attributes you use for filters and cards in the manifest under catalogue.attributes.

Your app runs the search (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 when results are personalised, ranked, drawn from a catalogue too large or too changeable to sync, or carry live availability and prices. A remote collection needs no sync. If every collection is remote, set catalogue.sync to false in the manifest and do not implement POST /catalogue. If a remote call fails, the guest sees a message that the list could not load and can try again. The step is not skipped.

For catalogue collections, POST /availability lists the items that are not free for the booking's slot. Remote collections do not use it. They mark an item with unavailable_label instead.

How a booking with an app flows

  1. Step. When the guest reaches your step, BookingNinja calls POST /guest-step with the booking's slot. You reply with blocks to draw: a collection, fields to fill in, a notice or text. You can also set how many items the guest may choose.
  2. Hold. When the guest chooses, BookingNinja calls POST /holds with the items, any answers, and an expires_at. You hold the items and reply with a hold_id and the priced lines. If an item has gone, reply 409 with the code unavailable. There is one live hold per booking. To extend or change a hold, BookingNinja sends a new request with replaces set to the current hold id.
  3. Price. The lines are added to the booking total, in the venue currency's minor units. The money goes to the venue. BookingNinja makes no separate charge for your app. Once the guest starts to pay, what your app adds to the price cannot change.
  4. Confirm. When the booking is complete, BookingNinja calls POST /holds/confirm with the hold_id. You reply with a reservation_id and, if you wish, a guest_summary that is shown on the confirmation page, in emails and on the manage-booking page. A failed confirm is retried every minute for 10 minutes, then the booking history records that it failed.
  5. Release. When an item is removed, the booking is cancelled or the hold is replaced, BookingNinja calls POST /holds/release. Reply 200 even if the hold is already gone.

If your app subscribes to events, BookingNinja also tells it about confirmed, updated, cancelled, checked-in, completed and no-show bookings. Staff see your blocks and buttons through POST /blocks and POST /actions. BookingNinja keeps the blocks it last received, so the booking list and the Gantt chart never wait for your app.

Signing requests

Every call BookingNinja makes to your app is a JSON POST signed with your app's signing secret. Reject any request that does not verify.

Header Value
X-BN-Signature t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
X-BN-Installation The installation's id, ins_…
X-BN-Request-Id Unique for each attempt. Useful in your logs.
Idempotency-Key The same on every retry of one operation

To verify a request:

signed_payload = t + "." + raw_body
expected       = hex(HMAC_SHA256(signing_secret, signed_payload))

Use the raw body exactly as it arrived, not a re-encoded copy. Compare expected with v1 in constant time. Reject the request if t is more than 5 minutes from your clock. A repeat with the same Idempotency-Key is a retry and must return the first response.

Timeouts

BookingNinja waits this long for each kind of call before it gives up.

Endpoint Seconds
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

When an app is slow or down

A guest is never left stuck because an app is slow. A call that times out, fails or returns something that does not match the contract counts as a failure. A reply larger than 2 MB is refused.

  • Guest step. If the guest step, availability or hold call fails, the step is skipped and the guest carries on with their booking.
  • Remote lists. The guest sees that the list could not load and can try again.
  • Staff blocks. Staff see the last blocks your app sent, marked as the last known details.
  • Confirm. A failed confirm is retried as described above.
  • Events. A failed event is retried after 1, 5, 15, 60, 180, 360, 720 minutes, which spreads the attempts over about a day.
  • Pausing. After 5 failures in a row, BookingNinja pauses the installation. A paused installation is not called, except for one call every 60 seconds to see whether your app has recovered.

Connecting a venue

The venue presses Connect in its admin. If your manifest has an install_url, BookingNinja first sends the browser there with an authorize_url in the query string. Sign the venue in, then send the browser on to authorize_url with your own state added. After the venue approves, BookingNinja sends the browser to your redirect_uri with a code, a return_url and your state. Check that state matches the browser session that started the flow. If you have no install_url there is no state, so ask the signed-in user to confirm before you link the installation.

Then call POST /api/v1/apps/oauth/token with the code. The code is single use and valid for 5 minutes. You receive an access token, a refresh token and the installation_id. The access token lasts 60 minutes and the refresh token 90 days. Each refresh token can be used once and returns a new pair. Finally, redirect the browser to return_url unchanged.

Your manifest asks for scopes. The venue sees this wording on the consent screen.

Scope What the venue sees
bookings:read See bookings that use this app
bookings:write_notes Add notes to bookings that use this app
bookings:alert Send alerts to your staff about bookings that use this app
guests:read See the guest's name and contact details on those bookings

Framed panel

JSON blocks cover most screens. For a screen they cannot express, the manifest can declare extension_points.detail_panel.url, an HTTPS page of your own. It is switched off unless BookingNinja enables it, so ask us before you build one.

When staff press the button, BookingNinja shows your page in a frame inside the booking, at {url}?token=<token>. The frame is sandboxed and sends no referrer. Your page must allow itself to be shown in a frame. The admin can be served from a partner's own domain, so do not limit framing to a single host. The token is a signed JWT, made when staff press the button and valid for five minutes.

Claim Meaning
iss bookingninja
aud Your app's id, app_…
installation The installation's id, ins_…
booking The booking's opaque reference, bkg_…
venue The venue's opaque id, ven_…
staff The staff member's display name
iat When the token was issued, in unix seconds
exp When it expires, five minutes after iat
jti A random id for this token

The token holds no internal ids, no email address and no guest details. To verify it, check the HS256 signature, check that aud is your app's id and that exp has not passed, and accept each jti only once. Call the API with your installation's bearer token if you need booking data. The token is not signed with your signing secret itself but with a key derived from it: the lowercase hex of HMAC-SHA256 over the text bookingninja-panel-v1, keyed with your signing secret. Use that hex string as the HS256 key.

Getting started

  1. In the BookingNinja admin, open Apps and choose Build your own app. Register your app with its manifest.
  2. Connect the app to your own venue and try it on a test booking.
  3. Submit the app for review.

The JSON Schema files are the source of truth. The reference below is generated from them. They are served at https://bookingninja.io/developers/contract/v1/, followed by the file name: common.schema.json, manifest.schema.json, oauth.schema.json, guest.schema.json, staff.schema.json and app-api.schema.json.

Endpoints

Endpoints marked BookingNinja calls your app are sent to {base_url}/{path} with the signing headers above. Endpoints marked Your app calls BookingNinja use the bearer token from the connect flow.

Connecting

POST /api/v1/apps/oauth/token

Exchanges the single-use authorization code BookingNinja redirected with for the installation's first access and refresh tokens, or exchanges a refresh token for a new pair.

  • Your app calls BookingNinja

Connecting a venue. If the manifest has install_url, BookingNinja first sends the browser there with authorize_url; the app redirects the browser to authorize_url with its own state added as a further query parameter. After the venue approves, BookingNinja redirects to the app's redirect_uri with code, return_url and, when the app supplied one, its state unchanged: the app MUST check it matches the browser session that started the flow. Without install_url there is no state, and the app must ask the signed-in user to confirm before linking. return_url is a signed BookingNinja admin URL and may be on a partner's own admin domain, so do not compare its host with the token endpoint's; the app redirects the browser to it unchanged, with no added query parameters. The app then calls POST /api/v1/apps/oauth/token with a JSON body. A token request repeated within 30 seconds (a lost response) is answered with a fresh pair. The token endpoint allows 20 requests a minute for each client id and IP address and 60 a minute for each IP address, and answers 429 rate_limited beyond that. A refused request is answered with {error: {code, message}} and one of the codes unsupported_grant_type, invalid_request (400), invalid_grant (400), invalid_client (401) or rate_limited (429).

Request body
Request: grant_type = authorization_code
Field Type Required Limits Description
grant_type string required always authorization_code authorization_code exchanges a code for the first token pair.
client_id string required The app's client id, issued when the app was registered.
client_secret string required The app's client secret, issued with the client id. Keep it on the app's server and never put it in a browser.
code string required Single use, valid for five minutes.
redirect_uri string required The app's redirect_uri from its manifest. It must equal the one the code was issued for.
{
    "grant_type": "authorization_code",
    "client_id": "cli_a1b2c3d4e5f6a7b8",
    "client_secret": "your-client-secret",
    "code": "code_5d2f8a1c9b3e7046",
    "redirect_uri": "https://apps.example.com/callback"
}
Request: grant_type = refresh_token
Field Type Required Limits Description
grant_type string required always refresh_token refresh_token exchanges a refresh token for a new token pair.
client_id string required The app's client id, issued when the app was registered.
client_secret string required The app's client secret, issued with the client id. Keep it on the app's server and never put it in a browser.
refresh_token string required Single use: each refresh returns a new pair. Replaying an old one long after it was used revokes every token of the installation.
{
    "grant_type": "refresh_token",
    "client_id": "cli_a1b2c3d4e5f6a7b8",
    "client_secret": "your-client-secret",
    "refresh_token": "rt_example_refresh_token"
}
Reply (200)
Field Type Required Limits Description
access_token string required The bearer token to send with every call to BookingNinja.
refresh_token string required Used once, at this endpoint, to get the next token pair.
token_type string required always Bearer Always Bearer.
expires_in integer required Seconds from now until the access token expires.
installation_id string required pattern ^ins_[a-z0-9]+$ Opaque id of the installation the tokens belong to. It is the same as context.installation_id.
scope string required Granted scopes, space separated.

Example

{
    "access_token": "at_example_access_token",
    "refresh_token": "rt_example_refresh_token",
    "token_type": "Bearer",
    "expires_in": 3600,
    "installation_id": "ins_7k2m9x4q1b8w",
    "scope": "bookings:read bookings:write_notes"
}

Catalogue and collections

POST /catalogue

Fetches the app's catalogue one page at a time, so BookingNinja can keep its own searchable copy of the items.

  • BookingNinja calls your app at {base_url}/catalogue
  • Timeout: 30 seconds

BookingNinja calls it when the app is connected, when the venue saves the app's settings, on a regular schedule and after the app calls POST /api/v1/apps/catalogue/changed. It follows next_cursor until there is none, up to 200 pages and 20,000 items in one sync. An app whose manifest sets catalogue.sync to false is never asked.

Request body
Field Type Required Limits Description
context context required Installation context only: context.booking is absent.
cursor string or null optional Where to continue from: the next_cursor of the previous page, or null for the first page.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        }
    }
}
Reply (200)
Field Type Required Limits Description
items array of object required at most 500 items One page of items.
items[].id string required at most 64 characters The item's id in the app. It names the item in selections, holds, filters and item_ids, and is compared exactly, so abc and ABC are different items.
items[].name string required at most 160 characters The title shown to guests and staff.
items[].summary string optional at most 200 characters A short line shown on cards and in lists.
items[].description string optional at most 4000 characters Longer text shown on the item's detail view.
items[].image_url string optional format uri The item's picture. Whether guests' browsers load it from here or from BookingNinja's own copy depends on images.delivery in the manifest.
items[].attributes object optional at most 20 keys Keys must be declared in manifest.catalogue.attributes. Values are strings, numbers, booleans or lists of those; anything nested is dropped.
items[].updated_at string optional format date-time UTC time the item last changed in the app. BookingNinja fetches the picture again when this or image_url changes.
items[].rating object optional A star rating shown on the card.
items[].rating.value number required from 0 to 5 From 0 to 5; halves are drawn.
items[].rating.count integer optional at least 0 How many ratings it is based on, shown as (128).
next_cursor string or null optional Opaque cursor for the next page, null or absent on the last page. It must change from page to page, or the sync stops.

Example

{
    "items": [
        {
            "id": "g_1042",
            "name": "Catan",
            "summary": "Trade, build and settle an island.",
            "description": "A game of trading and building for three or four players.",
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "attributes": {
                "players_min": 3,
                "players_max": 4
            }
        }
    ],
    "next_cursor": "c_9b3d52"
}

POST /collection

Returns one page of a remote collection for the search text, filters, sort and cursor the guest has chosen.

  • BookingNinja calls your app at {base_url}/collection
  • Timeout: 2 seconds

Used when a collection block has source remote, and by the staff item picker when the app keeps no synced catalogue. A failed or out-of-contract reply shows the guest that the list could not load, and does not skip the step.

Request body
Field Type Required Limits Description
context context required always has booking The booking the guest or staff member is choosing for.
collection_id string required The id of the remote collection block being shown.
query string optional at most 100 characters The search text, trimmed. Empty when nothing is typed.
filters object optional at most 12 keys The guest's current choices, keyed by filter id. A fits_range, max or min filter sends a number, one_of a string, any_of a list of strings, toggle a boolean.
sort object or null optional The key of the chosen sort option, with its direction.
sort.key string optional The key of the sort option chosen.
sort.direction string optional one of asc, desc The direction chosen for that option.
cursor string or null optional at most 500 characters The next_cursor of the previous page, or null for the first.
limit integer optional from 1 to 48 The most items to return: the block's page_size.
selected array of string optional Item ids already chosen in this step, so the app can keep them visible or exclude them.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        },
        "channel": "guest",
        "booking": {
            "ref": "bkg_9f3c1a7e5b2d8046",
            "status": "confirmed",
            "session": {
                "id": "ses_4d8a2c6e1b73",
                "name": "Evening play"
            },
            "date": "2026-12-05",
            "start": "18:00",
            "end": "20:00",
            "party_size": 4,
            "tables": [
                "Table 12"
            ],
            "guest": {
                "name": "Alex Morgan",
                "email": "[email protected]",
                "phone": "+441632960123"
            },
            "reservation_id": "res_5521"
        }
    },
    "collection_id": "all_games",
    "query": "catan",
    "filters": {
        "players": 4
    },
    "sort": {},
    "cursor": "c_8f2a41",
    "limit": 24
}
Reply (200)
Field Type Required Limits Description
items array of object required at most 48 items The page of items, in the order to show them.
items[].id string required at most 64 characters The item's id in the app. It names the item in selections, holds, filters and item_ids, and is compared exactly, so abc and ABC are different items.
items[].name string required at most 160 characters The title shown to guests and staff.
items[].summary string optional at most 200 characters A short line shown on cards and in lists.
items[].description string optional at most 4000 characters Longer text shown on the item's detail view.
items[].image_url string optional format uri The item's picture. Whether guests' browsers load it from here or from BookingNinja's own copy depends on images.delivery in the manifest.
items[].attributes object optional at most 20 keys Free-form for remote items; keys named by the block's card and detail are shown. Values are strings, numbers, booleans or lists of those; anything nested is dropped.
items[].updated_at string optional format date-time UTC time the item last changed in the app. BookingNinja fetches the picture again when this or image_url changes.
items[].unavailable_label string optional at most 40 characters Set to show the item greyed out and unselectable, e.g. Reserved. Remote collections do not use POST /availability.
items[].price_hint string optional at most 30 characters Shown on the card, e.g. £3. The price charged is always the one the hold returns.
items[].badges array of string optional at most 3 items; each at most 24 characters Short labels for the card, shown as given.
items[].max_quantity integer optional at least 1 Overrides selection.max_quantity_per_item for this item.
items[].rating object optional A star rating shown on the card.
items[].rating.value number required from 0 to 5 From 0 to 5; halves are drawn.
items[].rating.count integer optional at least 0 How many ratings it is based on, shown as (128).
next_cursor string or null optional at most 500 characters Opaque. Null or absent when there are no more.
total integer optional at least 0 Optional count of all matches, shown as N results.
filters array of object optional at most 8 items Optional. Replaces the collection's filters from now on.
filters[].id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the filter. The guest's choices are sent back keyed by this id.
filters[].label string required at most 40 characters The name of the filter, as the guest sees it.
filters[].type string required one of fits_range, max, min, one_of, any_of, toggle fits_range: the chosen number lies between min_key and max_key. max / min: the attribute is at most / at least the chosen number. one_of: the attribute equals the chosen option. any_of: a tags attribute contains any chosen option. toggle: an on/off switch sent as a boolean; remote collections only, since only the app knows what it means.
filters[].key string optional The item attribute the filter looks at, for max, min, one_of and any_of.
filters[].min_key string optional For fits_range: the attribute holding an item's lowest value, such as the fewest players.
filters[].max_key string optional For fits_range: the attribute holding an item's highest value, such as the most players.
filters[].choices array of number or string optional at most 30 items The values the guest can pick from, for max, min, one_of and any_of.
filters[].default any optional The value the filter starts on.
filters[].counts object optional Optional result count per choice, shown beside it. Keyed by the choice as a string.
filters[].counts.<key> integer optional at least 0 How many results have this choice.
sort array of object optional at most 6 items Optional. Replaces the collection's sort options.
sort[].label string required at most 40 characters The name of the option, as the guest sees it.
sort[].key string required name or a number attribute key.
sort[].direction string optional one of asc, desc; default asc Whether the sort runs from low to high (asc) or from high to low (desc).
heading string optional at most 80 characters Optional. Replaces the collection's heading, e.g. Results for "wing".
notice string optional at most 200 characters Optional message above the results, e.g. Showing games free at 18:00.
valid_for_seconds integer optional from 0 to 300 How long BookingNinja may reuse this answer for the same request. Default 15; 0 for never.

Example

{
    "items": [
        {
            "id": "g_1042",
            "name": "Catan",
            "summary": "Trade, build and settle an island.",
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "attributes": {
                "players_min": 3,
                "players_max": 4
            },
            "price_hint": "£3",
            "badges": [
                "New"
            ]
        }
    ],
    "next_cursor": "c_9b3d52",
    "total": 42,
    "notice": "Showing games free at 18:00.",
    "valid_for_seconds": 60
}

Guest step and holds

POST /guest-step

Asks the app what to show the guest on its step of the booking flow.

  • BookingNinja calls your app at {base_url}/guest-step
  • Timeout: 2 seconds

Sent when the guest reaches the step. If it fails, times out or returns something outside the contract, the step is skipped and the guest carries on without it.

Request body
Field Type Required Limits Description
context context required always has booking The booking the step is for. context.booking carries the slot: session, date, start, end and party size.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        },
        "channel": "guest",
        "booking": {
            "ref": "bkg_9f3c1a7e5b2d8046",
            "status": "confirmed",
            "session": {
                "id": "ses_4d8a2c6e1b73",
                "name": "Evening play"
            },
            "date": "2026-12-05",
            "start": "18:00",
            "end": "20:00",
            "party_size": 4,
            "tables": [
                "Table 12"
            ],
            "guest": {
                "name": "Alex Morgan",
                "email": "[email protected]",
                "phone": "+441632960123"
            },
            "reservation_id": "res_5521"
        }
    }
}
Reply (200)
Field Type Required Limits Description
skip boolean optional Set true to leave the step out of this booking, when the app has nothing to offer it (the wrong party size, a date it does not cover, a staff-made booking it does not serve). The guest moves straight on and nothing is held. It is not a fault: nothing counts against the app. Everything else in the reply is ignored. Leave it out to show the step.
title string optional at most 40 characters Heading of the step. Without it the manifest's default_label is used.
intro string optional at most 300 characters A line of introduction shown under the heading.
blocks array of guest block optional 1 to 30 items What to show on the step, from top to bottom. Up to 30. Every block id, and every field key inside fields blocks, must be unique across the step: an answer is sent under that name, so BookingNinja keeps the first and drops later duplicates.
selection object optional Limits on collection picks, counted across every collection block in the step. Options, plan and quantities blocks have their own limits and are not counted here.
selection.min integer optional at least 0; default 0 The fewest items the guest must choose. 0 makes choosing optional.
selection.max integer optional at least 1; default 1 The most different items the guest may choose across the step.
selection.max_quantity_per_item integer optional at least 1; default 1 The most of any one item the guest may ask for.
selection.price_hint string optional at most 60 characters A short note on price shown beside the choice. The price charged is always the one the holds reply returns.
skip_label string optional at most 30 characters The wording of the button that lets the guest carry on without choosing anything. BookingNinja supplies a default when it is left out.
Reply: type = collection in blocks[]

A list of items the guest can browse and choose from, taken from BookingNinja's copy of the catalogue or from the app live.

Field Type Required Limits Description
type string required always collection Always collection. It tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the block. Search and collection requests carry it as collection_id.
heading string optional at most 80 characters A heading shown above the list.
layout string optional one of grid, list, carousel; default grid How the items are laid out: as a grid of cards, as a vertical list or as a sideways carousel.
source string optional one of catalogue, remote; default catalogue catalogue (default): BookingNinja searches, filters, sorts and pages its synced copy of the catalogue. remote: the app does all of that itself. BookingNinja sends every change of search text, filter, sort or page to POST /collection and shows exactly what comes back, in the app's order, so results can be personalised, ranked, drawn from a catalogue too large or too changeable to sync, or carry live availability. A remote collection needs no catalogue sync. An app whose manifest sets catalogue.sync to false must make every collection remote.
item_ids array of string optional at most 100 items Show only these items, in this order. Omit to show the whole catalogue.
search object optional Settings for the search box above the list. A catalogue collection's text is always matched by BookingNinja on its synced copy; a remote collection's text is sent in query on POST /collection.
search.placeholder string optional at most 60 characters Hint text shown in the empty search box.
search.mode string optional one of local, remote Deprecated and ignored. To run search yourself, make the collection remote.
search.min_length integer optional from 0 to 10 Characters typed before a search is sent. Default 2.
filters array of object optional at most 8 items Initial filters. For a remote collection the app may replace them on any /collection response (for example to show result counts or narrow the choices).
filters[].id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the filter. The guest's choices are sent back keyed by this id.
filters[].label string required at most 40 characters The name of the filter, as the guest sees it.
filters[].type string required one of fits_range, max, min, one_of, any_of, toggle fits_range: the chosen number lies between min_key and max_key. max / min: the attribute is at most / at least the chosen number. one_of: the attribute equals the chosen option. any_of: a tags attribute contains any chosen option. toggle: an on/off switch sent as a boolean; remote collections only, since only the app knows what it means.
filters[].key string optional The item attribute the filter looks at, for max, min, one_of and any_of.
filters[].min_key string optional For fits_range: the attribute holding an item's lowest value, such as the fewest players.
filters[].max_key string optional For fits_range: the attribute holding an item's highest value, such as the most players.
filters[].choices array of number or string optional at most 30 items The values the guest can pick from, for max, min, one_of and any_of.
filters[].default any optional The value the filter starts on.
filters[].counts object optional Optional result count per choice, shown beside it. Keyed by the choice as a string.
filters[].counts.<key> integer optional at least 0 How many results have this choice.
sort array of object optional at most 6 items The sort options offered to the guest.
sort[].label string required at most 40 characters The name of the option, as the guest sees it.
sort[].key string required For a catalogue collection, name or a number attribute key. A remote collection may use any keys of its own, such as relevance.
sort[].direction string optional one of asc, desc; default asc Whether the sort runs from low to high (asc) or from high to low (desc).
card object optional How each item's card is drawn.
card.subtitle string optional at most 120 characters Text with {attribute_key} placeholders.
card.badges array of string optional at most 3 items Attribute keys shown as badges.
detail object optional What an item's detail view shows.
detail.show array of string optional at most 12 items description and attribute keys, in order.
page_size integer optional from 1 to 48 Items per page, 48 at most. Default 24.
empty_text string optional at most 160 characters Shown when there is nothing to list.
{
    "type": "collection",
    "id": "g_1042",
    "heading": "Choose a game",
    "layout": "grid",
    "source": "catalogue",
    "search": {
        "placeholder": "Search games",
        "mode": "local",
        "min_length": 2
    },
    "filters": [
        {
            "id": "players",
            "label": "Players",
            "type": "fits_range",
            "min_key": "players_min",
            "max_key": "players_max"
        }
    ],
    "sort": [
        {
            "label": "Name",
            "key": "name"
        }
    ],
    "card": {
        "subtitle": "{players_min} to {players_max} players",
        "badges": [
            "New"
        ]
    },
    "page_size": 24
}
Reply: type = fields in blocks[]

A small form the guest fills in on the step. The answers go to the app in answers on the holds request.

Field Type Required Limits Description
type string required always fields Always fields. It tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the block. A block with per_guest sends its answers under this id.
heading string optional at most 80 characters A heading shown above the form.
per_guest boolean optional default false Repeat the fields once per guest in the party.
fields array of field required 1 to 12 items The inputs in the form, in order.
{
    "type": "fields",
    "id": "g_1042",
    "heading": "Choose a game",
    "per_guest": false,
    "fields": [
        {
            "key": "shelf",
            "type": "text",
            "label": "Shelf",
            "help": "Where the game is kept.",
            "required": true,
            "max_length": 200
        }
    ]
}
Reply: type = options in blocks[]

A small fixed set of choices the guest picks from: packages, difficulty levels, room types, lanes, time slots within the visit. The answer is sent in answers under the block's id: one option id, or a list of them when multiple is true. Unlike a collection there is no search or paging; use it for up to 60 choices the app knows up front.

Field Type Required Limits Description
type string required always options Always options: it tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ The key the answer is sent under.
heading string optional at most 80 characters Shown above the choices.
help string optional at most 200 characters A line under the heading.
style string optional one of cards, tiles, list, pills, slots; default cards cards: picture, title, description and price, one or two per row. tiles: compact picture tiles. list: rows with a radio or tick. pills: a row of small buttons. slots: time-style buttons grouped under each option's group.
multiple boolean optional default false Let the guest pick more than one.
min integer optional at least 0 With multiple: the fewest the guest must pick.
max integer optional at least 1 With multiple: the most the guest may pick.
required boolean optional default false The guest cannot continue without choosing.
default any optional The option id chosen to begin with, or a list of ids when multiple is set. An unavailable or unknown id is ignored.
options array of object required 1 to 60 items The choices, in the order shown.
options[].id string required at most 64 characters Sent back as the answer. Unique within the block.
options[].title string required at most 80 characters The choice's name.
options[].description string optional at most 300 characters One or two sentences under the title.
options[].image_url string optional format uri; pattern ^https://; at most 500 characters A picture for card and tile styles. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
options[].price_hint string optional at most 30 characters Shown beside the choice, e.g. +£5. The price charged is always what the hold returns.
options[].badge string optional at most 24 characters A short label on the choice, e.g. Most popular.
options[].group string optional at most 60 characters slots style only: the heading this choice sits under, e.g. Morning.
options[].unavailable_label string optional at most 40 characters Set to show the choice greyed out and unselectable, e.g. Full.
{
    "type": "options",
    "id": "g_1042",
    "heading": "Choose a game",
    "help": "Where the game is kept.",
    "style": "cards",
    "multiple": false,
    "options": [
        {
            "id": "g_1042",
            "title": "Catan",
            "description": "A game of trading and building for three or four players.",
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "price_hint": "£3",
            "badge": "Badge"
        }
    ]
}
Reply: type = quantities in blocks[]

A list of things the guest sets a number for: shoe sizes, hire equipment, tokens, extras per head. The answer is sent in answers under the block's id as an object of row id to quantity; rows left at zero are left out.

Field Type Required Limits Description
type string required always quantities Always quantities: it tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ The key the answer is sent under.
heading string optional at most 80 characters Shown above the rows.
help string optional at most 200 characters A line under the heading.
total_min integer optional at least 0 The fewest the quantities must add up to.
total_max integer optional at least 1 The most the quantities may add up to. Use the party size to cap one-per-guest lists; the step is fetched again if the party size changes.
rows array of object required 1 to 40 items The rows, in the order shown.
rows[].id string required at most 64 characters The key this row's quantity is sent under.
rows[].label string required at most 80 characters What is being counted, e.g. Size 7 shoes.
rows[].description string optional at most 200 characters A line under the label.
rows[].image_url string optional format uri; pattern ^https://; at most 500 characters A small picture beside the row. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
rows[].price_hint string optional at most 30 characters Shown beside the row, e.g. £2 each.
rows[].min integer optional at least 0 The lowest quantity. Default 0. A row with a minimum above 0 always has at least that many and is always sent.
rows[].max integer optional from 1 to 999 The highest quantity. Default 20.
rows[].default integer optional at least 0 The quantity to begin with.
rows[].unavailable_label string optional at most 40 characters Set to show the row greyed out with its stepper disabled, e.g. None left.
{
    "type": "quantities",
    "id": "g_1042",
    "heading": "Choose a game",
    "help": "Where the game is kept.",
    "total_min": 0,
    "total_max": 1,
    "rows": [
        {
            "id": "g_1042",
            "label": "Shelf",
            "description": "A game of trading and building for three or four players.",
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "price_hint": "£3",
            "min": 1
        }
    ]
}
Reply: type = plan in blocks[]

A picture of a layout with places on it the guest can pick: lanes, pitches, karaoke rooms, desks, lockers, seats. The answer is sent in answers under the block's id: one spot id, or a list when multiple is true. Every spot is also listed as a button under the picture, so the block works without seeing or tapping the picture. Spots are rectangles or circles placed on the picture; a spot may not be rotated, so draw angled features into the picture and place an upright spot over each.

Field Type Required Limits Description
type string required always plan Always plan: it tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ The key the answer is sent under.
heading string optional at most 80 characters Shown above the plan.
help string optional at most 200 characters A line under the heading.
image_url string required format uri; pattern ^https://; at most 500 characters The plan itself. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
aspect_ratio number optional at most 10 The picture's width divided by its height, so space is reserved before it loads. Default 1.5.
multiple boolean optional default false Let the guest pick more than one spot.
min integer optional at least 0 With multiple: the fewest spots.
max integer optional at least 1 With multiple: the most spots.
required boolean optional default false The guest cannot continue without choosing.
spots array of object required 1 to 200 items The places on the plan.
spots[].id string required at most 64 characters Sent back as the answer.
spots[].label string required at most 40 characters The spot's name, e.g. Lane 4.
spots[].x number required from 0 to 100 Left edge, as a percentage of the picture's width.
spots[].y number required from 0 to 100 Top edge, as a percentage of the picture's height.
spots[].width number optional at most 100 Width as a percentage of the picture's width. Default 8.
spots[].height number optional at most 100 Height as a percentage of the picture's height. Default 8.
spots[].shape string optional one of rect, circle; default rect The outline drawn over the picture.
spots[].description string optional at most 200 characters Shown when the spot is chosen, e.g. Seats 6, next to the bar.
spots[].price_hint string optional at most 30 characters Shown with the spot, e.g. +£10.
spots[].unavailable_label string optional at most 40 characters Set to show the spot greyed out and unselectable, e.g. Taken.
{
    "type": "plan",
    "id": "g_1042",
    "heading": "Choose a game",
    "help": "Where the game is kept.",
    "image_url": "https://apps.example.com/images/g_1042.jpg",
    "aspect_ratio": 1,
    "multiple": false,
    "spots": [
        {
            "id": "g_1042",
            "label": "Reserved game",
            "x": 0,
            "y": 0,
            "width": 1,
            "height": 1,
            "shape": "rect",
            "description": "A game of trading and building for three or four players."
        }
    ]
}
Reply: type = notice in blocks[]

A short message shown on the step.

Field Type Required Limits Description
type string required always notice Always notice. It tells BookingNinja which kind of block this is.
text string required at most 300 characters The message.
tone string optional one of neutral, info, warning; default neutral How the message is coloured: plain, as information or as a warning.
{
    "type": "notice",
    "text": "Game reserved for this booking.",
    "tone": "neutral"
}
Reply: type = text in blocks[]

A heading or a paragraph of plain text on the step.

Field Type Required Limits Description
type string required always text Always text. It tells BookingNinja which kind of block this is.
text string required at most 600 characters The words to show.
style string optional one of heading, paragraph; default paragraph Whether the text is drawn as a heading or as a paragraph.
{
    "type": "text",
    "text": "Game reserved for this booking.",
    "style": "heading"
}
Reply: type = hero in blocks[]

A wide picture with a heading and a sentence, to open a step.

Field Type Required Limits Description
type string required always hero Always hero: it tells BookingNinja which kind of block this is.
image_url string required format uri; pattern ^https://; at most 500 characters The picture. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
alt string optional at most 160 characters What the picture shows.
heading string optional at most 80 characters Large words over or under the picture.
text string optional at most 300 characters A sentence under the heading.
{
    "type": "hero",
    "image_url": "https://apps.example.com/images/g_1042.jpg",
    "alt": "Alt",
    "heading": "Choose a game",
    "text": "Game reserved for this booking."
}

Pictures to look at: the room, the kit, the course. Nothing is chosen.

Field Type Required Limits Description
type string required always gallery Always gallery: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the pictures.
layout string optional one of carousel, grid; default carousel carousel: one row the guest swipes. grid: all pictures at once.
images array of object required 1 to 12 items The pictures, in order.
images[].image_url string required format uri; pattern ^https://; at most 500 characters The picture. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
images[].alt string optional at most 160 characters What the picture shows, for guests who cannot see it.
images[].caption string optional at most 160 characters A line under the picture.
{
    "type": "gallery",
    "heading": "Choose a game",
    "layout": "carousel",
    "images": [
        {
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "alt": "Alt",
            "caption": "Caption"
        }
    ]
}
Reply: type = steps in blocks[]

An ordered list of what will happen: an itinerary, how a session runs, what to do on arrival. Nothing is chosen.

Field Type Required Limits Description
type string required always steps Always steps: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the list.
items array of object required 1 to 12 items The steps, in order.
items[].title string required at most 80 characters What happens.
items[].text string optional at most 300 characters A sentence or two of detail.
items[].label string optional at most 24 characters A short marker beside the step, e.g. a time 18:00 or Step 1.
items[].icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
{
    "type": "steps",
    "heading": "Choose a game",
    "items": [
        {
            "title": "Catan",
            "text": "Game reserved for this booking.",
            "label": "Reserved game",
            "icon": "dice"
        }
    ]
}
Reply: type = details in blocks[]

Facts as label and value pairs: what is included, where to go, what was reserved.

Field Type Required Limits Description
type string required always details Always details: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the rows.
rows array of object required 1 to 12 items The pairs, in order.
rows[].label string required at most 60 characters What the fact is, e.g. Lane.
rows[].value string required at most 200 characters The fact itself, e.g. 4.
{
    "type": "details",
    "heading": "Choose a game",
    "rows": [
        {
            "label": "Shelf",
            "value": "A2"
        }
    ]
}
Reply: type = faq in blocks[]

Questions that open to show their answers: rules, what to bring, age limits.

Field Type Required Limits Description
type string required always faq Always faq: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the questions.
items array of object required 1 to 12 items The questions, in order. All start closed.
items[].question string required at most 160 characters The question.
items[].answer string required at most 1000 characters The answer, as plain text. Blank lines start a new paragraph.
{
    "type": "faq",
    "heading": "Choose a game",
    "items": [
        {
            "question": "Question",
            "answer": "Answer"
        }
    ]
}
Reply: type = table in blocks[]

A small table: a size chart, price tiers, a comparison. It scrolls sideways on a phone.

Field Type Required Limits Description
type string required always table Always table: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the table.
columns array of string required 1 to 6 items; each at most 40 characters The column headings.
rows array of array of string required 1 to 20 items; each at most 6 items The rows. Each is a list of cells, one per column.
highlight_row integer optional at least 0 The row to pick out, counted from 0, e.g. the one matching the guest's party size.
{
    "type": "table",
    "heading": "Choose a game",
    "columns": [
        "Columns"
    ],
    "rows": [
        [
            "Rows"
        ]
    ],
    "highlight_row": 0
}
Reply: type = meter in blocks[]

A bar showing how full something is: places left, level, progress.

Field Type Required Limits Description
type string required always meter Always meter: it tells BookingNinja which kind of block this is.
label string required at most 80 characters What is being measured, e.g. Places taken.
value number required at least 0 The amount so far.
max number required The amount that fills the bar.
caption string optional at most 120 characters Words under the bar, e.g. 3 of 8 places left.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "meter",
    "label": "Reserved game",
    "value": 0,
    "max": 4,
    "caption": "Caption",
    "tone": "neutral"
}

Links out to pages the app or venue hosts: house rules, a waiver, a how-to. Each opens in a new tab.

Field Type Required Limits Description
type string required always links Always links: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the links.
links array of object required 1 to 6 items The links, in order.
links[].label string required at most 60 characters The words of the link.
links[].url string required format uri; pattern ^https://; at most 500 characters Where it goes. HTTPS only.
{
    "type": "links",
    "heading": "Choose a game",
    "links": [
        {
            "label": "Reserved game",
            "url": "https://apps.example.com/help"
        }
    ]
}
Reply: type = divider in blocks[]

A thin line and some space between groups of blocks.

Field Type Required Limits Description
type string required always divider Always divider: it tells BookingNinja which kind of block this is.
{
    "type": "divider"
}

Example

{
    "skip": true,
    "title": "Choose a game",
    "intro": "Reserve a game for your table.",
    "blocks": [
        {
            "type": "collection",
            "id": "all_games",
            "heading": "Choose a game",
            "layout": "grid",
            "source": "catalogue",
            "search": {
                "placeholder": "Search games",
                "mode": "local",
                "min_length": 2
            },
            "filters": [
                {
                    "id": "players",
                    "label": "Players",
                    "type": "fits_range",
                    "min_key": "players_min",
                    "max_key": "players_max"
                }
            ],
            "sort": [
                {
                    "label": "Name",
                    "key": "name"
                }
            ],
            "card": {
                "subtitle": "{players_min} to {players_max} players",
                "badges": [
                    "New"
                ]
            },
            "page_size": 24
        },
        {
            "type": "fields",
            "id": "all_games",
            "heading": "Choose a game",
            "per_guest": false,
            "fields": [
                {
                    "key": "shelf",
                    "type": "text",
                    "label": "Shelf",
                    "help": "Where the game is kept.",
                    "required": true,
                    "max_length": 200
                }
            ]
        },
        {
            "type": "options",
            "id": "all_games",
            "heading": "Choose a game",
            "help": "Where the game is kept.",
            "style": "cards",
            "multiple": false,
            "options": [
                {
                    "id": "g_1042",
                    "title": "Catan",
                    "description": "A game of trading and building for three or four players.",
                    "image_url": "https://apps.example.com/images/g_1042.jpg",
                    "price_hint": "£3",
                    "badge": "Badge"
                }
            ]
        },
        {
            "type": "quantities",
            "id": "all_games",
            "heading": "Choose a game",
            "help": "Where the game is kept.",
            "total_min": 0,
            "total_max": 1,
            "rows": [
                {
                    "id": "g_1042",
                    "label": "Shelf",
                    "description": "A game of trading and building for three or four players.",
                    "image_url": "https://apps.example.com/images/g_1042.jpg",
                    "price_hint": "£3",
                    "min": 1
                }
            ]
        },
        {
            "type": "plan",
            "id": "all_games",
            "heading": "Choose a game",
            "help": "Where the game is kept.",
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "aspect_ratio": 1,
            "multiple": false,
            "spots": [
                {
                    "id": "g_1042",
                    "label": "Reserved game",
                    "x": 0,
                    "y": 0,
                    "width": 1,
                    "height": 1,
                    "shape": "rect",
                    "description": "A game of trading and building for three or four players."
                }
            ]
        },
        {
            "type": "notice",
            "text": "Pick a game to reserve for this booking.",
            "tone": "neutral"
        },
        {
            "type": "text",
            "text": "Pick a game to reserve for this booking.",
            "style": "heading"
        },
        {
            "type": "hero",
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "alt": "Alt",
            "heading": "Choose a game",
            "text": "Pick a game to reserve for this booking."
        },
        {
            "type": "gallery",
            "heading": "Choose a game",
            "layout": "carousel",
            "images": [
                {
                    "image_url": "https://apps.example.com/images/g_1042.jpg",
                    "alt": "Alt",
                    "caption": "Caption"
                }
            ]
        },
        {
            "type": "steps",
            "heading": "Choose a game",
            "items": [
                {
                    "title": "Catan",
                    "text": "Game reserved for this booking.",
                    "label": "Reserved game",
                    "icon": "dice"
                }
            ]
        },
        {
            "type": "details",
            "heading": "Choose a game",
            "rows": [
                {
                    "label": "Shelf",
                    "value": "A2"
                }
            ]
        },
        {
            "type": "faq",
            "heading": "Choose a game",
            "items": [
                {
                    "question": "Question",
                    "answer": "Answer"
                }
            ]
        },
        {
            "type": "table",
            "heading": "Choose a game",
            "columns": [
                "Columns"
            ],
            "rows": [
                [
                    "Rows"
                ]
            ],
            "highlight_row": 0
        },
        {
            "type": "meter",
            "label": "Reserved game",
            "value": 0,
            "max": 4,
            "caption": "Caption",
            "tone": "neutral"
        },
        {
            "type": "links",
            "heading": "Choose a game",
            "links": [
                {
                    "label": "Reserved game",
                    "url": "https://apps.example.com/help"
                }
            ]
        },
        {
            "type": "divider"
        }
    ]
}

POST /availability

Asks the app which items are taken for the booking's slot.

  • BookingNinja calls your app at {base_url}/availability
  • Timeout: 2 seconds

Sent straight after guest-step, on the same context. A remote collection does not use it: it marks items unavailable in its own collection replies.

Request body
Field Type Required Limits Description
context context required always has booking The booking whose slot is being checked.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        },
        "channel": "guest",
        "booking": {
            "ref": "bkg_9f3c1a7e5b2d8046",
            "status": "confirmed",
            "session": {
                "id": "ses_4d8a2c6e1b73",
                "name": "Evening play"
            },
            "date": "2026-12-05",
            "start": "18:00",
            "end": "20:00",
            "party_size": 4,
            "tables": [
                "Table 12"
            ],
            "guest": {
                "name": "Alex Morgan",
                "email": "[email protected]",
                "phone": "+441632960123"
            },
            "reservation_id": "res_5521"
        }
    }
}
Reply (200)
Field Type Required Limits Description
unavailable array of object required At most 2,000 entries are used; anything beyond that is ignored.
unavailable[].id string required The id of an item that is taken for the booking's slot.
unavailable[].label string optional at most 40 characters A short reason shown on the greyed-out item, such as Reserved.
valid_for_seconds integer optional from 0 to 300; default 30 Accepted and ignored.

Example

{
    "unavailable": [
        {
            "id": "g_2087",
            "label": "Reserved"
        }
    ],
    "valid_for_seconds": 60
}

POST /holds

Reserves the items the guest chose for the booking, until expires_at, and returns the priced lines that join the booking total.

  • BookingNinja calls your app at {base_url}/holds
  • Timeout: 3 seconds

Sent when the guest chooses. To extend or change a hold BookingNinja sends a new request with replaces set to the current hold id. A 409 unavailable reply tells the guest which items have gone.

Request body
Field Type Required Limits Description
context context required always has booking The booking the hold is for. context.booking.ref is the same from the first draft to the end of the booking.
items array of object required May be empty when the step has only fields blocks. Quantities respect selection.max_quantity_per_item from the guest-step response.
items[].id string required The id of a chosen item.
items[].quantity integer required at least 1 How many of that item the guest chose.
answers object optional Everything the guest answered other than collection picks, as one object. A fields block contributes its field keys; a field hidden by visible_when is not sent. A per_guest fields block instead sends, under its block id, a list with exactly one such object per guest in the party. An options or plan block sends, under its block id, the chosen id as a string, or a list of ids when the block has multiple set (never a list otherwise). A quantities block sends, under its block id, an object of row id to quantity; rows at zero are left out, and with nothing chosen the object is empty. A block the guest left unanswered is left out. BookingNinja refuses answers under names the step does not define, so an app never receives them.
replaces string or null optional A hold or reservation id this request supersedes. Replacing a hold releases it at once. Replacing a reservation keeps it until the new hold is confirmed, then releases it. The superseded hold's or reservation's own copies count as free when checking availability.
expires_at string required format date-time UTC time the hold should last until if it is not confirmed. The app must hold at least until then (BookingNinja accepts a hold that ends up to two minutes earlier). BookingNinja sets it a little beyond the time the guest has to finish booking, so a hold never lapses before the booking draft does.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        },
        "channel": "guest",
        "booking": {
            "ref": "bkg_9f3c1a7e5b2d8046",
            "status": "confirmed",
            "session": {
                "id": "ses_4d8a2c6e1b73",
                "name": "Evening play"
            },
            "date": "2026-12-05",
            "start": "18:00",
            "end": "20:00",
            "party_size": 4,
            "tables": [
                "Table 12"
            ],
            "guest": {
                "name": "Alex Morgan",
                "email": "[email protected]",
                "phone": "+441632960123"
            },
            "reservation_id": "res_5521"
        }
    },
    "items": [
        {
            "id": "g_1042",
            "quantity": 1
        }
    ],
    "answers": {
        "allergies": "none"
    },
    "expires_at": "2026-12-05T17:45:00Z"
}
Reply (200)
Field Type Required Limits Description
hold_id string required at most 64 characters The app's id for the hold. BookingNinja sends it back to confirm, replace or release the hold.
expires_at string required format date-time UTC time the app will let the hold lapse. It must not be earlier than the expires_at requested, less a tolerance of two minutes, or the hold is not accepted.
lines array of object required The priced lines to add to the booking total, one for each item or charge. An empty list adds nothing to the price.
lines[].item_id string or null optional The item the line is for, when there is one.
lines[].label string required at most 160 characters What the guest sees on the line of their basket.
lines[].quantity integer required at least 1 How many of the item the line covers.
lines[].unit_price integer required at least 0 The price of one. The line's total is quantity times this.

Example

{
    "hold_id": "hld_7f3a21",
    "expires_at": "2026-12-05T17:45:00Z",
    "lines": [
        {
            "item_id": "g_1042",
            "label": "Reserved game",
            "quantity": 1,
            "unit_price": 300
        }
    ]
}
Error reply (409)
Field Type Required Limits Description
error object required The error itself.
error.code string required always unavailable Always unavailable.
error.message string required A plain sentence for the guest, such as which game has gone.
error.unavailable array of string optional The ids of the items that are no longer available.

Example

{
    "error": {
        "code": "unavailable",
        "message": "That game is no longer available.",
        "unavailable": [
            "g_2087"
        ]
    }
}

POST /holds/confirm

Turns a live hold into a reservation once the guest has completed the booking.

  • BookingNinja calls your app at {base_url}/holds/confirm
  • Timeout: 5 seconds

If the app cannot be reached BookingNinja tries again once a minute for 10 minutes. A refusal is final: BookingNinja records the failure on the booking for staff to follow up.

Request body
Field Type Required Limits Description
context context required always has booking The booking being confirmed. Its window is the one the reservation is made for.
hold_id string required The hold to turn into a reservation: the hold_id from the holds reply.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        },
        "channel": "guest",
        "booking": {
            "ref": "bkg_9f3c1a7e5b2d8046",
            "status": "confirmed",
            "session": {
                "id": "ses_4d8a2c6e1b73",
                "name": "Evening play"
            },
            "date": "2026-12-05",
            "start": "18:00",
            "end": "20:00",
            "party_size": 4,
            "tables": [
                "Table 12"
            ],
            "guest": {
                "name": "Alex Morgan",
                "email": "[email protected]",
                "phone": "+441632960123"
            },
            "reservation_id": "res_5521"
        }
    },
    "hold_id": "hld_7f3a21"
}
Reply (200)
Field Type Required Limits Description
reservation_id string required at most 64 characters The app's id for the reservation. BookingNinja sends it back as context.booking.reservation_id and on release.
guest_summary object optional Stored and shown on the confirmation page, in emails and on the manage-booking page.
guest_summary.heading string optional at most 60 characters A title for the summary, such as what was reserved.
guest_summary.lines array of object required at most 10 items What to show, one line for each thing the guest chose.
guest_summary.lines[].label string required at most 160 characters The main text of the line, such as an item name.
guest_summary.lines[].note string optional at most 200 characters A second, smaller line of text.
guest_summary.lines[].image_item_id string optional A catalogue item whose picture to show beside the line.
guest_summary.blocks array of one of: details block, steps block, code block, links block optional at most 6 items Optional extra blocks under the lines: what was reserved, what happens on the day, a code to show. Shown on the confirmation page and the manage-booking page; emails show details, steps and the text of a code.
Reply: type = details in guest_summary.blocks[]

Facts as label and value pairs: what is included, where to go, what was reserved.

Field Type Required Limits Description
type string required always details Always details: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the rows.
rows array of object required 1 to 12 items The pairs, in order.
rows[].label string required at most 60 characters What the fact is, e.g. Lane.
rows[].value string required at most 200 characters The fact itself, e.g. 4.
{
    "type": "details",
    "heading": "Choose a game",
    "rows": [
        {
            "label": "Shelf",
            "value": "A2"
        }
    ]
}
Reply: type = steps in guest_summary.blocks[]

An ordered list of what will happen: an itinerary, how a session runs, what to do on arrival. Nothing is chosen.

Field Type Required Limits Description
type string required always steps Always steps: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the list.
items array of object required 1 to 12 items The steps, in order.
items[].title string required at most 80 characters What happens.
items[].text string optional at most 300 characters A sentence or two of detail.
items[].label string optional at most 24 characters A short marker beside the step, e.g. a time 18:00 or Step 1.
items[].icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
{
    "type": "steps",
    "heading": "Choose a game",
    "items": [
        {
            "title": "Catan",
            "text": "Game reserved for this booking.",
            "label": "Reserved game",
            "icon": "dice"
        }
    ]
}
Reply: type = code in guest_summary.blocks[]

A code the guest shows or types on the day: a door code, a locker number, a ticket reference.

Field Type Required Limits Description
type string required always code Always code: it tells BookingNinja which kind of block this is.
label string optional at most 60 characters What the code is for, e.g. Door code.
value string required at most 64 characters The code itself, shown large.
format string optional one of text, qr; default text text shows the characters. qr also draws a QR code of the value for scanning.
caption string optional at most 120 characters A line under the code, e.g. Valid from 17:45.
{
    "type": "code",
    "label": "Reserved game",
    "value": "a2",
    "format": "text",
    "caption": "Caption"
}

Links out to pages the app or venue hosts: house rules, a waiver, a how-to. Each opens in a new tab.

Field Type Required Limits Description
type string required always links Always links: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the links.
links array of object required 1 to 6 items The links, in order.
links[].label string required at most 60 characters The words of the link.
links[].url string required format uri; pattern ^https://; at most 500 characters Where it goes. HTTPS only.
{
    "type": "links",
    "heading": "Choose a game",
    "links": [
        {
            "label": "Reserved game",
            "url": "https://apps.example.com/help"
        }
    ]
}

Example

{
    "reservation_id": "res_5521",
    "guest_summary": {
        "heading": "Choose a game",
        "lines": [
            {
                "label": "Reserved game",
                "note": "Reserved by phone.",
                "image_item_id": "g_1042"
            }
        ],
        "blocks": [
            {
                "type": "details",
                "heading": "Choose a game",
                "rows": [
                    {
                        "label": "Shelf",
                        "value": "A2"
                    }
                ]
            },
            {
                "type": "steps",
                "heading": "Choose a game",
                "items": [
                    {
                        "title": "Catan",
                        "text": "Game reserved for this booking.",
                        "label": "Reserved game",
                        "icon": "dice"
                    }
                ]
            },
            {
                "type": "code",
                "label": "Reserved game",
                "value": "a2",
                "format": "text",
                "caption": "Caption"
            },
            {
                "type": "links",
                "heading": "Choose a game",
                "links": [
                    {
                        "label": "Reserved game",
                        "url": "https://apps.example.com/help"
                    }
                ]
            }
        ]
    }
}

POST /holds/release

Tells the app to let go of a hold, or of a reservation, that the booking no longer needs.

  • BookingNinja calls your app at {base_url}/holds/release
  • Timeout: 5 seconds

Sent without holding up the guest. A hold the app is never told to release lapses at its expires_at.

Request body
Field Type Required Limits Description
context context required always has booking The booking the hold or reservation belongs to.
hold_id string or null optional The hold to release, or null when only a reservation is named.
reservation_id string or null optional The reservation to release, or null when only a hold is named.
reason string optional one of removed, cancelled, replaced Why BookingNinja is releasing it. removed: the guest skipped the step after choosing items, 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 the app was still confirming it.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        },
        "channel": "guest",
        "booking": {
            "ref": "bkg_9f3c1a7e5b2d8046",
            "status": "confirmed",
            "session": {
                "id": "ses_4d8a2c6e1b73",
                "name": "Evening play"
            },
            "date": "2026-12-05",
            "start": "18:00",
            "end": "20:00",
            "party_size": 4,
            "tables": [
                "Table 12"
            ],
            "guest": {
                "name": "Alex Morgan",
                "email": "[email protected]",
                "phone": "+441632960123"
            },
            "reservation_id": "res_5521"
        }
    },
    "hold_id": "hld_7f3a21",
    "reservation_id": "res_5521",
    "reason": "removed"
}
Reply (200)

Any JSON object.

Example

{}

Settings

POST /settings/options

Asks the app for the choices of a settings field whose options is remote.

  • BookingNinja calls your app at {base_url}/settings/options
  • Timeout: 5 seconds

Sent when the venue's settings form needs the field's choices. values carries what is typed in the form so far, so the list can depend on other fields. If the call fails the field shows no choices.

Request body
Field Type Required Limits Description
context context required Sent in the body of almost every call BookingNinja makes to an app.
level string required one of venue, session Which settings form the field is on: the venue's or a session's.
key string required The key of the settings field whose choices are wanted.
values object optional The form's current, unsaved values.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        }
    },
    "level": "venue",
    "key": "default_shelf",
    "values": {
        "shelf": "A2"
    }
}
Reply (200)
Field Type Required Limits Description
options array of option required at most 200 items The choices, in the order to show them.

Example

{
    "options": [
        {
            "value": "a2",
            "label": "Shelf A2"
        }
    ]
}

POST /settings/validate

Lets the app check the settings a venue is saving before they are stored.

  • BookingNinja calls your app at {base_url}/settings/validate
  • Timeout: 5 seconds

Reply 200 to accept, or 422 with errors to refuse the save and show a message beside each field. A 404, a timeout or any other reply lets the save through.

Request body
Field Type Required Limits Description
context context required Sent in the body of almost every call BookingNinja makes to an app.
level string required one of venue, session Which settings form is being saved: the venue's or a session's.
values object required The values being saved, keyed by setting key, after BookingNinja's own checks.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        }
    },
    "level": "venue",
    "values": {
        "shelf": "A2"
    }
}
Reply (200)

Any JSON object.

Example

{}
Error reply (422)
Field Type Required Limits Description
errors object required Field key to message.
errors.<key> string optional at most 300 characters

Example

{
    "errors": {
        "shelf": "Choose a shelf from the list."
    }
}

Staff blocks and actions

POST /blocks

Asks the app for the blocks to show staff on some bookings: badges on the Gantt chart, chips in the booking list and blocks in the booking drawer.

  • BookingNinja calls your app at {base_url}/blocks
  • Timeout: 3 seconds

Sent for a batch of bookings of up to 100 when the Gantt chart or list needs fresh blocks, and for one booking when staff open its drawer. The Gantt and list blocks are cached for valid_for_seconds and shown from the cache.

Request body
Field Type Required Limits Description
context context required Sent in the body of almost every call BookingNinja makes to an app.
slots array of string required no repeats; each one of gantt_bar, list_row, drawer The slots BookingNinja wants blocks for. It only asks for slots the manifest declares.
bookings array of booking required at most 100 items The bookings to return blocks for. For the drawer this is the one booking being opened.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        }
    },
    "slots": [
        "gantt_bar",
        "list_row"
    ],
    "bookings": [
        {
            "ref": "bkg_9f3c1a7e5b2d8046",
            "status": "confirmed",
            "session": {
                "id": "ses_4d8a2c6e1b73",
                "name": "Evening play"
            },
            "date": "2026-12-05",
            "start": "18:00",
            "end": "20:00",
            "party_size": 4,
            "tables": [
                "Table 12"
            ],
            "guest": {
                "name": "Alex Morgan",
                "email": "[email protected]",
                "phone": "+441632960123"
            },
            "reservation_id": "res_5521"
        }
    ]
}
Reply (200)
Field Type Required Limits Description
bookings object required Keyed by booking ref. An empty answer is the object {}. Labels longer than the limits are rejected, so shorten them before sending.
bookings.<key> object optional The blocks for one booking, by slot. Leave out a slot with nothing to show.
bookings.<key>.gantt_bar array of object optional at most 1 item The badge shown on the booking's bar in the Gantt chart.
bookings.<key>.gantt_bar[].type string required always badge Always badge. It tells BookingNinja which kind of block this is.
bookings.<key>.gantt_bar[].label string required at most 24 characters The badge's text.
bookings.<key>.gantt_bar[].icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
bookings.<key>.gantt_bar[].tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
bookings.<key>.gantt_bar[].tooltip string optional at most 160 characters Text shown when staff point at the badge.
bookings.<key>.list_row array of object optional at most 2 items The chips shown on the booking's row in the booking list.
bookings.<key>.list_row[].type string required always chip Always chip. It tells BookingNinja which kind of block this is.
bookings.<key>.list_row[].label string required at most 30 characters The chip's text.
bookings.<key>.list_row[].tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
bookings.<key>.drawer array of staff block optional at most 20 items The blocks shown in the booking's detail drawer, from top to bottom.
valid_for_seconds integer optional from 30 to 3600; default 300 How long BookingNinja may show these blocks before asking again.
Reply: type = badge in bookings.<key>.drawer[]

A small coloured label, shown on a Gantt bar or in the drawer.

Field Type Required Limits Description
type string required always badge Always badge. It tells BookingNinja which kind of block this is.
label string required at most 24 characters The badge's text.
icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
tooltip string optional at most 160 characters Text shown when staff point at the badge.
{
    "type": "badge",
    "label": "Reserved game",
    "icon": "dice",
    "tone": "neutral",
    "tooltip": "A game is reserved for this booking."
}
Reply: type = chip in bookings.<key>.drawer[]

A short pill of text, shown in a list row or in the drawer.

Field Type Required Limits Description
type string required always chip Always chip. It tells BookingNinja which kind of block this is.
label string required at most 30 characters The chip's text.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "chip",
    "label": "Reserved game",
    "tone": "neutral"
}
Reply: type = text in bookings.<key>.drawer[]

A paragraph of plain text in the drawer.

Field Type Required Limits Description
type string required always text Always text. It tells BookingNinja which kind of block this is.
text string required at most 400 characters The words to show.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "text",
    "text": "Game reserved for this booking.",
    "tone": "neutral"
}
Reply: type = key_value in bookings.<key>.drawer[]

A list of labelled values in the drawer, such as a shelf and a condition.

Field Type Required Limits Description
type string required always key_value Always key_value. It tells BookingNinja which kind of block this is.
rows array of object required at most 12 items The label and value pairs, in order.
rows[].label string required at most 40 characters What the value is.
rows[].value string required at most 160 characters The value.
{
    "type": "key_value",
    "rows": [
        {
            "label": "Shelf",
            "value": "A2"
        }
    ]
}
Reply: type = image_list in bookings.<key>.drawer[]

A list of items with their pictures, in the drawer.

Field Type Required Limits Description
type string required always image_list Always image_list. It tells BookingNinja which kind of block this is.
items array of object required at most 10 items The entries, in order.
items[].item_id string optional A catalogue item whose image to show.
items[].title string required at most 160 characters The entry's main text.
items[].subtitle string optional at most 160 characters A second, smaller line of text.
{
    "type": "image_list",
    "items": [
        {
            "item_id": "g_1042",
            "title": "Catan",
            "subtitle": "3 to 4 players"
        }
    ]
}
Reply: type = actions in bookings.<key>.drawer[]

Buttons staff can press. Each press sends POST /actions. Only shown when the manifest declares staff_actions.

Field Type Required Limits Description
type string required always actions Always actions. It tells BookingNinja which kind of block this is.
actions array of object required at most 5 items The buttons, in order.
actions[].id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the button and is sent back as action_id. It must be unique across the whole drawer, or the first button with the id wins.
actions[].label string required at most 30 characters The text on the button.
actions[].style string optional one of default, primary, danger; default default How the button looks: ordinary, emphasised or as a warning of something destructive.
actions[].confirm string optional at most 200 characters Ask staff to confirm with this wording first.
actions[].input string optional one of collection, fields collection: open the catalogue picker first. fields: open a small form first.
actions[].fields array of field optional at most 8 items The form's fields, for input of fields.
{
    "type": "actions",
    "actions": [
        {
            "id": "swap_game",
            "label": "Swap game",
            "style": "default",
            "confirm": "Remove this game from the booking?"
        }
    ]
}
Reply: type = alert in bookings.<key>.drawer[]

A boxed message that stands out: something staff must do or know.

Field Type Required Limits Description
type string required always alert Always alert: it tells BookingNinja which kind of block this is.
title string optional at most 60 characters Bold first line.
text string required at most 400 characters The message.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "alert",
    "title": "Catan",
    "text": "Game reserved for this booking.",
    "tone": "neutral"
}
Reply: type = stat in bookings.<key>.drawer[]

One figure shown large with a label: points balance, visits, minutes left.

Field Type Required Limits Description
type string required always stat Always stat: it tells BookingNinja which kind of block this is.
label string required at most 40 characters What the figure is.
value string required at most 40 characters The figure, as it should read, e.g. 320 or £12.50.
caption string optional at most 80 characters Small words under it.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
{
    "type": "stat",
    "label": "Reserved game",
    "value": "a2",
    "caption": "Caption",
    "tone": "neutral",
    "icon": "dice"
}
Reply: type = meter in bookings.<key>.drawer[]

A bar showing how full something is.

Field Type Required Limits Description
type string required always meter Always meter: it tells BookingNinja which kind of block this is.
label string required at most 80 characters What is being measured.
value number required at least 0 The amount so far.
max number required The amount that fills the bar.
caption string optional at most 120 characters Words under the bar.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "meter",
    "label": "Reserved game",
    "value": 0,
    "max": 4,
    "caption": "Caption",
    "tone": "neutral"
}
Reply: type = timeline in bookings.<key>.drawer[]

What has happened, newest first or oldest first as the app sends it: handed out, returned, checked.

Field Type Required Limits Description
type string required always timeline Always timeline: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
items array of object required 1 to 20 items The entries, in the order shown.
items[].title string required at most 80 characters What happened.
items[].text string optional at most 200 characters Detail.
items[].at string optional at most 24 characters When, as the app wants it to read, e.g. 18:02 or Tue 3 Dec.
items[].tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "timeline",
    "heading": "Choose a game",
    "items": [
        {
            "title": "Catan",
            "text": "Game reserved for this booking.",
            "at": "At",
            "tone": "neutral"
        }
    ]
}
Reply: type = table in bookings.<key>.drawer[]

A small table.

Field Type Required Limits Description
type string required always table Always table: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the table.
columns array of string required 1 to 6 items; each at most 40 characters The column headings.
rows array of array of string required 1 to 20 items; each at most 6 items The rows. Each is a list of cells, one per column.
{
    "type": "table",
    "heading": "Choose a game",
    "columns": [
        "Columns"
    ],
    "rows": [
        [
            "Rows"
        ]
    ]
}
Reply: type = tags in bookings.<key>.drawer[]

A row of small labels.

Field Type Required Limits Description
type string required always tags Always tags: it tells BookingNinja which kind of block this is.
tags array of object required 1 to 12 items The labels, in order.
tags[].label string required at most 30 characters The words.
tags[].tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "tags",
    "tags": [
        {
            "label": "Reserved game",
            "tone": "neutral"
        }
    ]
}
Reply: type = people in bookings.<key>.drawer[]

People attached to the booking on the app's side: an instructor, a host, a guide.

Field Type Required Limits Description
type string required always people Always people: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
people array of object required 1 to 6 items The people, in order.
people[].name string required at most 80 characters Their name.
people[].role string optional at most 60 characters What they are doing, e.g. Instructor.
people[].note string optional at most 160 characters A line of detail.
people[].image_url string optional format uri; pattern ^https://; at most 500 characters A small photo. HTTPS only; shown through BookingNinja's own copy unless the manifest asks for direct delivery.
{
    "type": "people",
    "heading": "Choose a game",
    "people": [
        {
            "name": "Catan",
            "role": "Role",
            "note": "Reserved by phone.",
            "image_url": "https://apps.example.com/images/g_1042.jpg"
        }
    ]
}
Reply: type = checklist in bookings.<key>.drawer[]

A list staff tick off: kit handed over, waiver seen, briefing done. Ticking a box that has an action_id presses that action with input.values set to {item, done}; a box without one is display only.

Field Type Required Limits Description
type string required always checklist Always checklist: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
items array of object required 1 to 20 items The lines, in order.
items[].id string required at most 64 characters Sent as item when the box is ticked.
items[].label string required at most 120 characters What to check.
items[].done boolean required Whether it is ticked.
items[].action_id string optional pattern ^[a-z][a-z0-9_]{0,39}$ The action pressed when staff tick or untick the box. Use an id of its own, not one a button in this drawer already uses: a line that shares a button's id is shown as a read-only tick. BookingNinja treats the id as an action without a button, so the app must declare staff_actions.
{
    "type": "checklist",
    "heading": "Choose a game",
    "items": [
        {
            "id": "g_1042",
            "label": "Reserved game",
            "done": true,
            "action_id": "swap_game"
        }
    ]
}

Pictures staff may need: the item's condition, a photo taken at handover.

Field Type Required Limits Description
type string required always gallery Always gallery: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the pictures.
images array of object required 1 to 8 items The pictures, in order.
images[].image_url string required format uri; pattern ^https://; at most 500 characters The picture. HTTPS only.
images[].alt string optional at most 160 characters What it shows.
images[].caption string optional at most 160 characters A line under it.
{
    "type": "gallery",
    "heading": "Choose a game",
    "images": [
        {
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "alt": "Alt",
            "caption": "Caption"
        }
    ]
}
Reply: type = code in bookings.<key>.drawer[]

A code staff need: a locker number, a door code, a reference to quote.

Field Type Required Limits Description
type string required always code Always code: it tells BookingNinja which kind of block this is.
label string optional at most 60 characters What the code is for.
value string required at most 64 characters The code, shown large.
format string optional one of text, qr; default text text shows the characters; qr also draws a QR code.
caption string optional at most 120 characters A line under it.
{
    "type": "code",
    "label": "Reserved game",
    "value": "a2",
    "format": "text",
    "caption": "Caption"
}

Links out to the app's own pages for this booking. Each opens in a new tab.

Field Type Required Limits Description
type string required always links Always links: it tells BookingNinja which kind of block this is.
links array of object required 1 to 6 items The links, in order.
links[].label string required at most 60 characters The words of the link.
links[].url string required format uri; pattern ^https://; at most 500 characters Where it goes. HTTPS only.
{
    "type": "links",
    "links": [
        {
            "label": "Reserved game",
            "url": "https://apps.example.com/help"
        }
    ]
}

Example

{
    "bookings": {
        "bkg_9f3c1a7e5b2d8046": {
            "gantt_bar": [
                {
                    "type": "badge",
                    "label": "Reserved game",
                    "icon": "dice",
                    "tone": "neutral",
                    "tooltip": "A game is reserved for this booking."
                }
            ],
            "list_row": [
                {
                    "type": "chip",
                    "label": "Reserved game",
                    "tone": "neutral"
                }
            ],
            "drawer": [
                {
                    "type": "badge",
                    "label": "Reserved game",
                    "icon": "dice",
                    "tone": "neutral",
                    "tooltip": "A game is reserved for this booking."
                },
                {
                    "type": "chip",
                    "label": "Reserved game",
                    "tone": "neutral"
                },
                {
                    "type": "text",
                    "text": "Game reserved for this booking.",
                    "tone": "neutral"
                },
                {
                    "type": "key_value",
                    "rows": [
                        {
                            "label": "Shelf",
                            "value": "A2"
                        }
                    ]
                },
                {
                    "type": "image_list",
                    "items": [
                        {
                            "item_id": "g_1042",
                            "title": "Catan",
                            "subtitle": "3 to 4 players"
                        }
                    ]
                },
                {
                    "type": "actions",
                    "actions": [
                        {
                            "id": "swap_game",
                            "label": "Swap game",
                            "style": "default",
                            "confirm": "Remove this game from the booking?"
                        }
                    ]
                },
                {
                    "type": "alert",
                    "title": "Catan",
                    "text": "Game reserved for this booking.",
                    "tone": "neutral"
                },
                {
                    "type": "stat",
                    "label": "Reserved game",
                    "value": "a2",
                    "caption": "Caption",
                    "tone": "neutral",
                    "icon": "dice"
                },
                {
                    "type": "meter",
                    "label": "Reserved game",
                    "value": 0,
                    "max": 4,
                    "caption": "Caption",
                    "tone": "neutral"
                },
                {
                    "type": "timeline",
                    "heading": "Choose a game",
                    "items": [
                        {
                            "title": "Catan",
                            "text": "Game reserved for this booking.",
                            "at": "At",
                            "tone": "neutral"
                        }
                    ]
                },
                {
                    "type": "table",
                    "heading": "Choose a game",
                    "columns": [
                        "Columns"
                    ],
                    "rows": [
                        [
                            "Rows"
                        ]
                    ]
                },
                {
                    "type": "tags",
                    "tags": [
                        {
                            "label": "Reserved game",
                            "tone": "neutral"
                        }
                    ]
                },
                {
                    "type": "people",
                    "heading": "Choose a game",
                    "people": [
                        {
                            "name": "Catan",
                            "role": "Role",
                            "note": "Reserved by phone.",
                            "image_url": "https://apps.example.com/images/g_1042.jpg"
                        }
                    ]
                },
                {
                    "type": "checklist",
                    "heading": "Choose a game",
                    "items": [
                        {
                            "id": "g_1042",
                            "label": "Reserved game",
                            "done": true,
                            "action_id": "swap_game"
                        }
                    ]
                },
                {
                    "type": "gallery",
                    "heading": "Choose a game",
                    "images": [
                        {
                            "image_url": "https://apps.example.com/images/g_1042.jpg",
                            "alt": "Alt",
                            "caption": "Caption"
                        }
                    ]
                },
                {
                    "type": "code",
                    "label": "Reserved game",
                    "value": "a2",
                    "format": "text",
                    "caption": "Caption"
                },
                {
                    "type": "links",
                    "links": [
                        {
                            "label": "Reserved game",
                            "url": "https://apps.example.com/help"
                        }
                    ]
                }
            ]
        }
    },
    "valid_for_seconds": 60
}

POST /actions

Runs a button the app showed staff in the booking drawer.

  • BookingNinja calls your app at {base_url}/actions
  • Timeout: 5 seconds

BookingNinja sends the button's id, the staff member's name and any input, and applies the reply: a toast, new drawer blocks, new price lines, a changed reservation or a new guest summary. A button is accepted only if the app last offered it on that booking.

Request body
Field Type Required Limits Description
context context required always has booking A context that must carry booking. Used by every call that is about one booking.
action_id string required The id of the button staff pressed.
actor object required The staff member who pressed the button.
actor.name string required The staff member's display name, for the app's own records.
input object optional What staff entered, when the button asked for input. Absent for a button with none.
input.items array of object optional For a button with input of collection: the items staff chose in the picker.
input.items[].id string required The id of a chosen item.
input.items[].quantity integer required at least 1 How many of that item staff chose.
input.values object optional For an action with a form: the staff member's answers keyed by field key, after BookingNinja's own checks. For a checklist tick: {item, done}, the line's id and whether it is now ticked.

Example

{
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        },
        "channel": "guest",
        "booking": {
            "ref": "bkg_9f3c1a7e5b2d8046",
            "status": "confirmed",
            "session": {
                "id": "ses_4d8a2c6e1b73",
                "name": "Evening play"
            },
            "date": "2026-12-05",
            "start": "18:00",
            "end": "20:00",
            "party_size": 4,
            "tables": [
                "Table 12"
            ],
            "guest": {
                "name": "Alex Morgan",
                "email": "[email protected]",
                "phone": "+441632960123"
            },
            "reservation_id": "res_5521"
        }
    },
    "action_id": "swap_game",
    "actor": {
        "name": "Sam Taylor"
    },
    "input": {
        "items": [
            {
                "id": "g_1042",
                "quantity": 1
            }
        ]
    }
}
Reply (200)
Field Type Required Limits Description
message string optional at most 200 characters Shown to staff as a toast.
drawer array of staff block optional at most 10 items Replaces the drawer blocks. Gantt and list blocks are re-fetched.
lines array or null optional Null or absent leaves the booking's app lines unchanged. A list replaces them.
reservation_id string or null optional Set when the action replaced the reservation. Null clears it.
guest_summary guest summary or null optional Replaces the stored summary. Null clears it.
guest_summary.heading string optional at most 60 characters A title for the summary, such as what was reserved.
guest_summary.lines array of object required at most 10 items What to show, one line for each thing the guest chose.
guest_summary.lines[].label string required at most 160 characters The main text of the line, such as an item name.
guest_summary.lines[].note string optional at most 200 characters A second, smaller line of text.
guest_summary.lines[].image_item_id string optional A catalogue item whose picture to show beside the line.
guest_summary.blocks array of one of: details block, steps block, code block, links block optional at most 6 items Optional extra blocks under the lines: what was reserved, what happens on the day, a code to show. Shown on the confirmation page and the manage-booking page; emails show details, steps and the text of a code.
Reply: type = badge in drawer[]

A small coloured label, shown on a Gantt bar or in the drawer.

Field Type Required Limits Description
type string required always badge Always badge. It tells BookingNinja which kind of block this is.
label string required at most 24 characters The badge's text.
icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
tooltip string optional at most 160 characters Text shown when staff point at the badge.
{
    "type": "badge",
    "label": "Reserved game",
    "icon": "dice",
    "tone": "neutral",
    "tooltip": "A game is reserved for this booking."
}
Reply: type = chip in drawer[]

A short pill of text, shown in a list row or in the drawer.

Field Type Required Limits Description
type string required always chip Always chip. It tells BookingNinja which kind of block this is.
label string required at most 30 characters The chip's text.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "chip",
    "label": "Reserved game",
    "tone": "neutral"
}
Reply: type = text in drawer[]

A paragraph of plain text in the drawer.

Field Type Required Limits Description
type string required always text Always text. It tells BookingNinja which kind of block this is.
text string required at most 400 characters The words to show.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "text",
    "text": "Game reserved for this booking.",
    "tone": "neutral"
}
Reply: type = key_value in drawer[]

A list of labelled values in the drawer, such as a shelf and a condition.

Field Type Required Limits Description
type string required always key_value Always key_value. It tells BookingNinja which kind of block this is.
rows array of object required at most 12 items The label and value pairs, in order.
rows[].label string required at most 40 characters What the value is.
rows[].value string required at most 160 characters The value.
{
    "type": "key_value",
    "rows": [
        {
            "label": "Shelf",
            "value": "A2"
        }
    ]
}
Reply: type = image_list in drawer[]

A list of items with their pictures, in the drawer.

Field Type Required Limits Description
type string required always image_list Always image_list. It tells BookingNinja which kind of block this is.
items array of object required at most 10 items The entries, in order.
items[].item_id string optional A catalogue item whose image to show.
items[].title string required at most 160 characters The entry's main text.
items[].subtitle string optional at most 160 characters A second, smaller line of text.
{
    "type": "image_list",
    "items": [
        {
            "item_id": "g_1042",
            "title": "Catan",
            "subtitle": "3 to 4 players"
        }
    ]
}
Reply: type = actions in drawer[]

Buttons staff can press. Each press sends POST /actions. Only shown when the manifest declares staff_actions.

Field Type Required Limits Description
type string required always actions Always actions. It tells BookingNinja which kind of block this is.
actions array of object required at most 5 items The buttons, in order.
actions[].id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the button and is sent back as action_id. It must be unique across the whole drawer, or the first button with the id wins.
actions[].label string required at most 30 characters The text on the button.
actions[].style string optional one of default, primary, danger; default default How the button looks: ordinary, emphasised or as a warning of something destructive.
actions[].confirm string optional at most 200 characters Ask staff to confirm with this wording first.
actions[].input string optional one of collection, fields collection: open the catalogue picker first. fields: open a small form first.
actions[].fields array of field optional at most 8 items The form's fields, for input of fields.
{
    "type": "actions",
    "actions": [
        {
            "id": "swap_game",
            "label": "Swap game",
            "style": "default",
            "confirm": "Remove this game from the booking?"
        }
    ]
}
Reply: type = alert in drawer[]

A boxed message that stands out: something staff must do or know.

Field Type Required Limits Description
type string required always alert Always alert: it tells BookingNinja which kind of block this is.
title string optional at most 60 characters Bold first line.
text string required at most 400 characters The message.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "alert",
    "title": "Catan",
    "text": "Game reserved for this booking.",
    "tone": "neutral"
}
Reply: type = stat in drawer[]

One figure shown large with a label: points balance, visits, minutes left.

Field Type Required Limits Description
type string required always stat Always stat: it tells BookingNinja which kind of block this is.
label string required at most 40 characters What the figure is.
value string required at most 40 characters The figure, as it should read, e.g. 320 or £12.50.
caption string optional at most 80 characters Small words under it.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
{
    "type": "stat",
    "label": "Reserved game",
    "value": "a2",
    "caption": "Caption",
    "tone": "neutral",
    "icon": "dice"
}
Reply: type = meter in drawer[]

A bar showing how full something is.

Field Type Required Limits Description
type string required always meter Always meter: it tells BookingNinja which kind of block this is.
label string required at most 80 characters What is being measured.
value number required at least 0 The amount so far.
max number required The amount that fills the bar.
caption string optional at most 120 characters Words under the bar.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "meter",
    "label": "Reserved game",
    "value": 0,
    "max": 4,
    "caption": "Caption",
    "tone": "neutral"
}
Reply: type = timeline in drawer[]

What has happened, newest first or oldest first as the app sends it: handed out, returned, checked.

Field Type Required Limits Description
type string required always timeline Always timeline: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
items array of object required 1 to 20 items The entries, in the order shown.
items[].title string required at most 80 characters What happened.
items[].text string optional at most 200 characters Detail.
items[].at string optional at most 24 characters When, as the app wants it to read, e.g. 18:02 or Tue 3 Dec.
items[].tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "timeline",
    "heading": "Choose a game",
    "items": [
        {
            "title": "Catan",
            "text": "Game reserved for this booking.",
            "at": "At",
            "tone": "neutral"
        }
    ]
}
Reply: type = table in drawer[]

A small table.

Field Type Required Limits Description
type string required always table Always table: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the table.
columns array of string required 1 to 6 items; each at most 40 characters The column headings.
rows array of array of string required 1 to 20 items; each at most 6 items The rows. Each is a list of cells, one per column.
{
    "type": "table",
    "heading": "Choose a game",
    "columns": [
        "Columns"
    ],
    "rows": [
        [
            "Rows"
        ]
    ]
}
Reply: type = tags in drawer[]

A row of small labels.

Field Type Required Limits Description
type string required always tags Always tags: it tells BookingNinja which kind of block this is.
tags array of object required 1 to 12 items The labels, in order.
tags[].label string required at most 30 characters The words.
tags[].tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "tags",
    "tags": [
        {
            "label": "Reserved game",
            "tone": "neutral"
        }
    ]
}
Reply: type = people in drawer[]

People attached to the booking on the app's side: an instructor, a host, a guide.

Field Type Required Limits Description
type string required always people Always people: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
people array of object required 1 to 6 items The people, in order.
people[].name string required at most 80 characters Their name.
people[].role string optional at most 60 characters What they are doing, e.g. Instructor.
people[].note string optional at most 160 characters A line of detail.
people[].image_url string optional format uri; pattern ^https://; at most 500 characters A small photo. HTTPS only; shown through BookingNinja's own copy unless the manifest asks for direct delivery.
{
    "type": "people",
    "heading": "Choose a game",
    "people": [
        {
            "name": "Catan",
            "role": "Role",
            "note": "Reserved by phone.",
            "image_url": "https://apps.example.com/images/g_1042.jpg"
        }
    ]
}
Reply: type = checklist in drawer[]

A list staff tick off: kit handed over, waiver seen, briefing done. Ticking a box that has an action_id presses that action with input.values set to {item, done}; a box without one is display only.

Field Type Required Limits Description
type string required always checklist Always checklist: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
items array of object required 1 to 20 items The lines, in order.
items[].id string required at most 64 characters Sent as item when the box is ticked.
items[].label string required at most 120 characters What to check.
items[].done boolean required Whether it is ticked.
items[].action_id string optional pattern ^[a-z][a-z0-9_]{0,39}$ The action pressed when staff tick or untick the box. Use an id of its own, not one a button in this drawer already uses: a line that shares a button's id is shown as a read-only tick. BookingNinja treats the id as an action without a button, so the app must declare staff_actions.
{
    "type": "checklist",
    "heading": "Choose a game",
    "items": [
        {
            "id": "g_1042",
            "label": "Reserved game",
            "done": true,
            "action_id": "swap_game"
        }
    ]
}

Pictures staff may need: the item's condition, a photo taken at handover.

Field Type Required Limits Description
type string required always gallery Always gallery: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the pictures.
images array of object required 1 to 8 items The pictures, in order.
images[].image_url string required format uri; pattern ^https://; at most 500 characters The picture. HTTPS only.
images[].alt string optional at most 160 characters What it shows.
images[].caption string optional at most 160 characters A line under it.
{
    "type": "gallery",
    "heading": "Choose a game",
    "images": [
        {
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "alt": "Alt",
            "caption": "Caption"
        }
    ]
}
Reply: type = code in drawer[]

A code staff need: a locker number, a door code, a reference to quote.

Field Type Required Limits Description
type string required always code Always code: it tells BookingNinja which kind of block this is.
label string optional at most 60 characters What the code is for.
value string required at most 64 characters The code, shown large.
format string optional one of text, qr; default text text shows the characters; qr also draws a QR code.
caption string optional at most 120 characters A line under it.
{
    "type": "code",
    "label": "Reserved game",
    "value": "a2",
    "format": "text",
    "caption": "Caption"
}

Links out to the app's own pages for this booking. Each opens in a new tab.

Field Type Required Limits Description
type string required always links Always links: it tells BookingNinja which kind of block this is.
links array of object required 1 to 6 items The links, in order.
links[].label string required at most 60 characters The words of the link.
links[].url string required format uri; pattern ^https://; at most 500 characters Where it goes. HTTPS only.
{
    "type": "links",
    "links": [
        {
            "label": "Reserved game",
            "url": "https://apps.example.com/help"
        }
    ]
}
Reply: type = details in guest_summary.blocks[]

Facts as label and value pairs: what is included, where to go, what was reserved.

Field Type Required Limits Description
type string required always details Always details: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the rows.
rows array of object required 1 to 12 items The pairs, in order.
rows[].label string required at most 60 characters What the fact is, e.g. Lane.
rows[].value string required at most 200 characters The fact itself, e.g. 4.
{
    "type": "details",
    "heading": "Choose a game",
    "rows": [
        {
            "label": "Shelf",
            "value": "A2"
        }
    ]
}
Reply: type = steps in guest_summary.blocks[]

An ordered list of what will happen: an itinerary, how a session runs, what to do on arrival. Nothing is chosen.

Field Type Required Limits Description
type string required always steps Always steps: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the list.
items array of object required 1 to 12 items The steps, in order.
items[].title string required at most 80 characters What happens.
items[].text string optional at most 300 characters A sentence or two of detail.
items[].label string optional at most 24 characters A short marker beside the step, e.g. a time 18:00 or Step 1.
items[].icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
{
    "type": "steps",
    "heading": "Choose a game",
    "items": [
        {
            "title": "Catan",
            "text": "Game reserved for this booking.",
            "label": "Reserved game",
            "icon": "dice"
        }
    ]
}
Reply: type = code in guest_summary.blocks[]

A code the guest shows or types on the day: a door code, a locker number, a ticket reference.

Field Type Required Limits Description
type string required always code Always code: it tells BookingNinja which kind of block this is.
label string optional at most 60 characters What the code is for, e.g. Door code.
value string required at most 64 characters The code itself, shown large.
format string optional one of text, qr; default text text shows the characters. qr also draws a QR code of the value for scanning.
caption string optional at most 120 characters A line under the code, e.g. Valid from 17:45.
{
    "type": "code",
    "label": "Reserved game",
    "value": "a2",
    "format": "text",
    "caption": "Caption"
}

Links out to pages the app or venue hosts: house rules, a waiver, a how-to. Each opens in a new tab.

Field Type Required Limits Description
type string required always links Always links: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the links.
links array of object required 1 to 6 items The links, in order.
links[].label string required at most 60 characters The words of the link.
links[].url string required format uri; pattern ^https://; at most 500 characters Where it goes. HTTPS only.
{
    "type": "links",
    "heading": "Choose a game",
    "links": [
        {
            "label": "Reserved game",
            "url": "https://apps.example.com/help"
        }
    ]
}

Example

{
    "message": "Done.",
    "drawer": [
        {
            "type": "badge",
            "label": "Reserved game",
            "icon": "dice",
            "tone": "neutral",
            "tooltip": "A game is reserved for this booking."
        },
        {
            "type": "chip",
            "label": "Reserved game",
            "tone": "neutral"
        },
        {
            "type": "text",
            "text": "Game reserved for this booking.",
            "tone": "neutral"
        },
        {
            "type": "key_value",
            "rows": [
                {
                    "label": "Shelf",
                    "value": "A2"
                }
            ]
        },
        {
            "type": "image_list",
            "items": [
                {
                    "item_id": "g_1042",
                    "title": "Catan",
                    "subtitle": "3 to 4 players"
                }
            ]
        },
        {
            "type": "actions",
            "actions": [
                {
                    "id": "swap_game",
                    "label": "Swap game",
                    "style": "default",
                    "confirm": "Remove this game from the booking?"
                }
            ]
        },
        {
            "type": "alert",
            "title": "Catan",
            "text": "Game reserved for this booking.",
            "tone": "neutral"
        },
        {
            "type": "stat",
            "label": "Reserved game",
            "value": "a2",
            "caption": "Caption",
            "tone": "neutral",
            "icon": "dice"
        },
        {
            "type": "meter",
            "label": "Reserved game",
            "value": 0,
            "max": 4,
            "caption": "Caption",
            "tone": "neutral"
        },
        {
            "type": "timeline",
            "heading": "Choose a game",
            "items": [
                {
                    "title": "Catan",
                    "text": "Game reserved for this booking.",
                    "at": "At",
                    "tone": "neutral"
                }
            ]
        }
    ],
    "lines": [
        {
            "item_id": "g_1042",
            "label": "Reserved game",
            "quantity": 1,
            "unit_price": 300
        }
    ]
}
Error reply (422)
Field Type Required Limits Description
errors object required Field key to message.
errors.<key> string optional at most 300 characters

Example

{
    "errors": {
        "shelf": "Choose a shelf from the list."
    }
}
Error reply (409)
Field Type Required Limits Description
error object required The error itself.
error.code string required A short code in lower case with underscores, such as invalid_request or not_found. The codes BookingNinja itself returns are listed under each endpoint.
error.message string required at most 300 characters A plain sentence saying what went wrong, without internal detail.

Example

{
    "error": {
        "code": "unavailable",
        "message": "That game is no longer available."
    }
}

Events

POST /events

Tells the app that something happened to a booking or to the installation.

  • BookingNinja calls your app at {base_url}/events
  • Timeout: 10 seconds

Sent only for the event types the manifest lists. Delivery is at least once: a failed delivery is retried with growing gaps for about 24 hours, and the Idempotency-Key is the event_id, so a repeat is the same event. A 2xx reply with a JSON object as its body counts as delivered.

Request body
Field Type Required Limits Description
event_id string required pattern ^evt_[a-z0-9]+$ Unique id of the event. A repeated delivery of the same event carries the same id, so use it to ignore duplicates.
type string required one of booking.confirmed, booking.updated, booking.cancelled, booking.checked_in, booking.completed, booking.no_show, installation.settings_updated, installation.uninstalled What happened. booking.confirmed: the app's hold on the booking is now a reservation. booking.updated: the booking's party size, date, time, tables or session changed, as listed in changed. booking.cancelled: a booking the app had a reservation for was cancelled. booking.checked_in, booking.completed and booking.no_show: the guest arrived, left or did not come. installation.settings_updated: the venue saved the app's settings. installation.uninstalled: the venue disconnected the app, the only event sent after that.
occurred_at string required format date-time UTC time the event happened.
changed array of string optional each one of date, time, party_size, tables, session booking.updated only.
context context required The installation and, for booking events, the booking as it was when the event was queued.

Example

{
    "event_id": "evt_6b1f9d3a8c24",
    "type": "booking.confirmed",
    "occurred_at": "2026-12-05T17:30:00Z",
    "context": {
        "installation_id": "ins_7k2m9x4q1b8w",
        "venue": {
            "id": "ven_3h8d5n2p7c4a",
            "name": "The Old Mill",
            "timezone": "Europe/London",
            "currency": "GBP",
            "locale": "en-GB"
        },
        "settings": {
            "venue": {
                "default_shelf": "A"
            },
            "session": {}
        }
    }
}
Reply (200)

Any JSON object.

Example

{}

Calling BookingNinja

The calls your app makes to BookingNinja, as opposed to the calls BookingNinja makes to your app. Every path is under /api/v1/apps on the same host as the token endpoint, and every body is JSON. Send Authorization: Bearer <access_token>, using a token from POST /api/v1/apps/oauth/token (see oauth.schema.json). A token is valid for expires_in seconds from the moment it is issued; once it has expired, or the venue has disconnected the app, calls fail with 401 invalid_token, so exchange the refresh token for a new pair at the same endpoint. A token belongs to one installation, which is one app on one venue, and can never reach another installation's data. Every error is a JSON body of the form {error: {code, message}} with the HTTP status given for each endpoint. Calls are limited to 300 a minute for each installation, and beyond that BookingNinja answers 429 rate_limited with a Retry-After header giving the seconds to wait.

GET /api/v1/apps/installation

Returns the installation the bearer token belongs to: the app, the venue and the scopes the venue granted.

  • Your app calls BookingNinja

Needs no scope. A useful first call after the code exchange, to check the venue's name, time zone and currency and the scopes that were granted. Counts towards the installation's limit of 300 requests a minute.

Reply (200)
Field Type Required Limits Description
installation_id string required pattern ^ins_[a-z0-9]+$ Opaque id of the installation, which is one app on one venue.
app object required The app the installation is of.
app.id string required pattern ^app_[a-z0-9]+$ The app's opaque id.
app.name string required The app name as venues see it.
venue object required The venue the installation is connected to.
venue.id string required pattern ^ven_[a-z0-9]+$ Opaque. Never the internal store id.
venue.name string required The venue's name, as its guests see it.
venue.timezone string required IANA time zone name of the venue, such as Europe/London. Dates and times in a call are wall-clock time in this zone unless a field says UTC.
venue.currency string required pattern ^[A-Z]{3}$ ISO 4217 code of the venue currency. Every amount of money in a call is in this currency.
venue.locale string required BCP 47 language tag of the venue, such as en-GB.
scopes array of string required each one of bookings:read, bookings:write_notes, bookings:alert, guests:read The scopes the venue granted this installation. A call that needs a scope missing from this list is refused with 403 insufficient_scope.
status string required one of active The installation's status. It is always active, because a token for an installation in any other state is refused with 401 invalid_token.

Example

{
    "installation_id": "ins_7k2m9x4q1b8w",
    "app": {
        "id": "app_k3m9x2q7",
        "name": "Board Sheep"
    },
    "venue": {
        "id": "ven_3h8d5n2p7c4a",
        "name": "The Old Mill",
        "timezone": "Europe/London",
        "currency": "GBP",
        "locale": "en-GB"
    },
    "scopes": [
        "bookings:read",
        "bookings:write_notes"
    ],
    "status": "active"
}
Error reply (401)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_token Always invalid_token. Get a new token pair with the refresh token.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_token",
        "message": "The access token is missing, invalid, expired or revoked."
    }
}
Error reply (403)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of app_suspended, not_available app_suspended: BookingNinja has suspended the app. not_available: Apps is not available for the venue, for example because the venue has closed.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "app_suspended",
        "message": "This app has been suspended."
    }
}
Error reply (429)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of rate_limited Always rate_limited.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests. Retry after the Retry-After header."
    }
}

POST /api/v1/apps/catalogue/changed

Tells BookingNinja that the app's catalogue has changed, so it fetches POST /catalogue again and refreshes its synced copy.

  • Your app calls BookingNinja

Needs no scope and ignores any body. At most one sync is queued a minute for each installation: a call within that minute is still answered 202 and is not queued again. If the manifest sets catalogue.sync to false, nothing is queued and the answer is still 202. Counts towards the installation's limit of 300 requests a minute.

Reply (202)
Field Type Required Limits Description
queued boolean required always true Always true. It does not mean a sync was started by this call: a call within a minute of an earlier one is accepted and not queued again.

Example

{
    "queued": true
}
Error reply (401)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_token Always invalid_token. Get a new token pair with the refresh token.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_token",
        "message": "The access token is missing, invalid, expired or revoked."
    }
}
Error reply (403)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of app_suspended, not_available app_suspended: BookingNinja has suspended the app. not_available: Apps is not available for the venue, for example because the venue has closed.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "app_suspended",
        "message": "This app has been suspended."
    }
}
Error reply (429)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of rate_limited Always rate_limited.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests. Retry after the Retry-After header."
    }
}

POST /api/v1/apps/blocks/refresh

Tells BookingNinja that the app's Gantt bar or list row blocks changed for some bookings, so it fetches them again with POST /blocks.

  • Your app calls BookingNinja

Needs no scope. The drawer is not refreshed by this call: BookingNinja asks for it when staff open the booking. Counts towards the installation's limit of 300 requests a minute.

Request body
Field Type Required Limits Description
bookings array of string required at most 100 items; each at most 32 characters The bkg_ refs of the bookings, as BookingNinja sent them to the app. A ref that is not one of this installation's is ignored without saying so.

Example

{
    "bookings": [
        "bkg_9f3c1a7e5b2d8046"
    ]
}
Reply (202)
Field Type Required Limits Description
queued integer required at least 0 How many of the listed bookings belong to this installation and will have their blocks fetched again. It is 0 when the list is empty or the manifest declares neither the gantt_bar nor the list_row slot.

Example

{
    "queued": 0
}
Error reply (401)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_token Always invalid_token. Get a new token pair with the refresh token.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_token",
        "message": "The access token is missing, invalid, expired or revoked."
    }
}
Error reply (403)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of app_suspended, not_available app_suspended: BookingNinja has suspended the app. not_available: Apps is not available for the venue, for example because the venue has closed.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "app_suspended",
        "message": "This app has been suspended."
    }
}
Error reply (422)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_request Always invalid_request.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_request",
        "message": "`bookings` must be a list of at most 100 booking refs."
    }
}
Error reply (429)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of rate_limited Always rate_limited.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests. Retry after the Retry-After header."
    }
}

GET /api/v1/apps/bookings/{ref}

Returns one booking the app is attached to, in the shape of context.booking, with the data the app stored on it.

  • Your app calls BookingNinja

Needs the bookings:read scope. A token only reaches bookings of its own installation, that is, bookings of its own venue that the app is attached to. A booking is reachable while the app's link to it is live (held, being confirmed, confirmed, or with its confirmation pending or failed), and for 30 days after the link ended (released, declined by the guest or skipped because the app could not be reached). Any other ref, whether it never existed or belongs to another app or venue, gets the same 404 not_found. guest is included only when the venue also granted guests:read, the booking is not a draft and the app's link is live. tables is included on every booking that is not a draft. Counts towards the installation's limit of 300 requests a minute.

Reply (200)
Field Type Required Limits Description
booking booking required The booking, in the same shape as context.booking. It follows the access rule above: guest is left out once the app's link to the booking has ended.
app_data object or null required The data the app last saved with PUT /bookings/{ref}/data, or null when it has saved none.

Example

{
    "booking": {
        "ref": "bkg_9f3c1a7e5b2d8046",
        "status": "confirmed",
        "session": {
            "id": "ses_4d8a2c6e1b73",
            "name": "Evening play"
        },
        "date": "2026-12-05",
        "start": "18:00",
        "end": "20:00",
        "party_size": 4,
        "tables": [
            "Table 12"
        ],
        "guest": {
            "name": "Alex Morgan",
            "email": "[email protected]",
            "phone": "+441632960123"
        },
        "reservation_id": "res_5521"
    },
    "app_data": {
        "shelf": "A2",
        "checked": true
    }
}
Error reply (401)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_token Always invalid_token. Get a new token pair with the refresh token.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_token",
        "message": "The access token is missing, invalid, expired or revoked."
    }
}
Error reply (403)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of insufficient_scope, app_suspended, not_available insufficient_scope: the installation was not granted the scope the endpoint needs. app_suspended: BookingNinja has suspended the app. not_available: Apps is not available for the venue, for example because the venue has closed.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "insufficient_scope",
        "message": "This installation has not been granted the bookings:read scope."
    }
}
Error reply (404)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of not_found Always not_found.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "not_found",
        "message": "No such booking."
    }
}
Error reply (429)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of rate_limited Always rate_limited.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests. Retry after the Retry-After header."
    }
}

POST /api/v1/apps/bookings/{ref}/notes

Adds a note to the booking's history, where venue staff see it as the app's name followed by the note.

  • Your app calls BookingNinja

Needs the bookings:write_notes scope. A token only reaches bookings of its own installation, that is, bookings of its own venue that the app is attached to. A booking is reachable while the app's link to it is live (held, being confirmed, confirmed, or with its confirmation pending or failed), and for 30 days after the link ended (released, declined by the guest or skipped because the app could not be reached). Any other ref, whether it never existed or belongs to another app or venue, gets the same 404 not_found. Every call adds a new note, so sending the same note twice adds it twice. Counts towards the installation's limit of 300 requests a minute.

Request body
Field Type Required Limits Description
note string required 1 to 1000 characters The note's text. Markup is stripped, and a note that is empty afterwards is refused.

Example

{
    "note": "Reserved by phone."
}
Reply (201)
Field Type Required Limits Description
created boolean required always true Always true.

Example

{
    "created": true
}
Error reply (401)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_token Always invalid_token. Get a new token pair with the refresh token.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_token",
        "message": "The access token is missing, invalid, expired or revoked."
    }
}
Error reply (403)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of insufficient_scope, app_suspended, not_available insufficient_scope: the installation was not granted the scope the endpoint needs. app_suspended: BookingNinja has suspended the app. not_available: Apps is not available for the venue, for example because the venue has closed.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "insufficient_scope",
        "message": "This installation has not been granted the bookings:read scope."
    }
}
Error reply (404)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of not_found Always not_found.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "not_found",
        "message": "No such booking."
    }
}
Error reply (422)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_request Always invalid_request.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_request",
        "message": "`bookings` must be a list of at most 100 booking refs."
    }
}
Error reply (429)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of rate_limited Always rate_limited.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests. Retry after the Retry-After header."
    }
}

POST /api/v1/apps/bookings/{ref}/alerts

Raises an alert for the venue's staff about the booking, for something that needs a person now ("Game due back in 10 minutes", "Lane 4 needs attention"). The alert is written to the booking's history and handed to the venue's own notification triggers, which decide who is told and how.

  • Your app calls BookingNinja

Needs the bookings:alert scope. A token only reaches bookings of its own installation, that is, bookings of its own venue that the app is attached to. A booking is reachable while the app's link to it is live (held, being confirmed, confirmed, or with its confirmation pending or failed), and for 30 days after the link ended (released, declined by the guest or skipped because the app could not be reached). Any other ref, whether it never existed or belongs to another app or venue, gets the same 404 not_found. A booking that is cancelled, or that finished more than 24 hours ago, takes no more alerts: 409 booking_closed. BookingNinja never contacts anyone by itself: the venue chooses who is told, and by which channels (the notification bell in the admin, a phone alert, email or text message), with a trigger on the event "An app raised an alert". delivered in the reply says whether such a trigger will tell anyone about this alert; when it is false the alert is only recorded on the booking. The same alert sent again for the same booking within 10 minutes is answered 200 with the first alert's id and delivered, and nothing else happens: it is the same alert when its key matches, or, when it has no key, when its title and message match. Use a key such as due-back-<reservation id> so a retry never reaches staff twice. Each installation may raise 30 alerts an hour, and 6 an hour for any one booking; past either limit the call is refused with 429 rate_limited and a Retry-After header giving the seconds to wait. Answers 200 for a repeat do not count towards these limits. Counts towards the installation's limit of 300 requests a minute.

Request body
Field Type Required Limits Description
title string required 1 to 60 characters What staff need to know, in a few words. It is the alert's headline wherever it is shown, and the start of a text message. Markup is stripped, and a title that is empty afterwards is refused.
message string optional at most 200 characters Optional. A sentence or two more, shown under the title. Markup is stripped; an empty message is the same as none.
level string optional one of info, warning, urgent; default info How pressing it is: info (the default), warning or urgent. Staff see it on the alert, and the venue's own trigger can say more; it does not change who is told.
key string optional at most 64 characters Optional. The app's own name for this alert, so a repeat is recognised: the same key for the same booking within 10 minutes is answered with the first alert and does nothing more. Without a key, an alert with the same title and message is treated as the same alert.

Example

{
    "title": "Game due back in 10 minutes",
    "message": "Catan is due back at the counter at 20:00.",
    "level": "warning",
    "key": "due-back-res_4f2a"
}
Reply (201)
Field Type Required Limits Description
id string required BookingNinja's id for the alert. A repeat within 10 minutes returns the first alert's id.
delivered boolean required True when the venue has an active trigger for "An app raised an alert" that matches this booking and sends it somewhere, so someone will be told. False when no trigger will: the alert is only recorded on the booking's history.

Example

{
    "id": "alr_7k2m9q4x1c8v5b3n",
    "delivered": true
}
Error reply (401)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_token Always invalid_token. Get a new token pair with the refresh token.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_token",
        "message": "The access token is missing, invalid, expired or revoked."
    }
}
Error reply (403)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of insufficient_scope, app_suspended, not_available insufficient_scope: the installation was not granted the scope the endpoint needs. app_suspended: BookingNinja has suspended the app. not_available: Apps is not available for the venue, for example because the venue has closed.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "insufficient_scope",
        "message": "This installation has not been granted the bookings:read scope."
    }
}
Error reply (404)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of not_found Always not_found.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "not_found",
        "message": "No such booking."
    }
}
Error reply (409)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of booking_closed Always booking_closed.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "booking_closed",
        "message": "This booking is cancelled or has finished, so it takes no more alerts."
    }
}
Error reply (422)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_request Always invalid_request.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_request",
        "message": "`bookings` must be a list of at most 100 booking refs."
    }
}
Error reply (429)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of rate_limited Always rate_limited.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "rate_limited",
        "message": "Too many alerts for this booking. Retry after the Retry-After header."
    }
}

PUT /api/v1/apps/bookings/{ref}/data

Saves the app's own data on the booking, replacing what it saved before.

  • Your app calls BookingNinja

Needs no scope beyond a valid token. A token only reaches bookings of its own installation, that is, bookings of its own venue that the app is attached to. A booking is reachable while the app's link to it is live (held, being confirmed, confirmed, or with its confirmation pending or failed), and for 30 days after the link ended (released, declined by the guest or skipped because the app could not be reached). Any other ref, whether it never existed or belongs to another app or venue, gets the same 404 not_found. The data is kept for the app alone: BookingNinja never reads or shows it. Saving to a link that has ended does not extend its 30 days. Counts towards the installation's limit of 300 requests a minute.

Request body
Field Type Required Limits Description
data object or null required The app's own data for the booking, as one JSON object of at most 4,096 bytes once encoded. Null or {} clears it. A list is refused.

Example

{
    "data": {
        "shelf": "A2",
        "checked": true
    }
}
Reply (200)
Field Type Required Limits Description
app_data object or null required The stored data, or null when it was cleared or never set.

Example

{
    "app_data": {
        "shelf": "A2",
        "checked": true
    }
}
Error reply (401)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_token Always invalid_token. Get a new token pair with the refresh token.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_token",
        "message": "The access token is missing, invalid, expired or revoked."
    }
}
Error reply (403)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of app_suspended, not_available app_suspended: BookingNinja has suspended the app. not_available: Apps is not available for the venue, for example because the venue has closed.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "app_suspended",
        "message": "This app has been suspended."
    }
}
Error reply (404)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of not_found Always not_found.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "not_found",
        "message": "No such booking."
    }
}
Error reply (422)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of invalid_request Always invalid_request.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "invalid_request",
        "message": "`bookings` must be a list of at most 100 booking refs."
    }
}
Error reply (429)
Field Type Required Limits Description
error object required The error itself.
error.code string required one of rate_limited Always rate_limited.
error.message string required A plain sentence saying what went wrong.

Example

{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests. Retry after the Retry-After header."
    }
}

Shared shapes

Context

common.schema.json#/$defs/context

Sent in the body of almost every call BookingNinja makes to an app.

Field Type Required Limits Description
installation_id string required pattern ^ins_[a-z0-9]+$ Opaque id of the installation, which is one app on one venue. It is the same value as the X-BN-Installation header and the installation_id in the token reply.
venue object required The venue the installation is connected to.
venue.id string required pattern ^ven_[a-z0-9]+$ Opaque. Never the internal store id.
venue.name string required The venue's name, as its guests see it.
venue.timezone string required IANA time zone name of the venue, such as Europe/London. Dates and times in a call are wall-clock time in this zone unless a field says UTC.
venue.currency string required pattern ^[A-Z]{3}$ ISO 4217 code of the venue currency. Every amount of money in a call is in this currency.
venue.locale string required BCP 47 language tag of the venue, such as en-GB.
settings object required The settings the venue has saved for this app, as defined by the manifest's settings fields.
settings.venue object required The venue-level settings, keyed by setting key. A setting the venue has not saved carries its manifest default.
settings.session object required Empty when the call is not about one session.
channel string optional one of guest, staff Who is at the screen when a person is filling the step in. guest: the guest, on the venue's booking page or their own booking page. staff: a member of the venue's staff adding the app's step to a booking from the admin, where only collection and fields blocks are shown. Sent with guest-step and collection, and with availability and holds when a person is choosing; absent when BookingNinja acts on its own (moving a reservation with the booking) and on every other call.
booking booking optional The booking this call is about. Present on every call about one booking, and absent on calls about the catalogue, the settings or a batch of bookings.

Example

{
    "installation_id": "ins_7k2m9x4q1b8w",
    "venue": {
        "id": "ven_3h8d5n2p7c4a",
        "name": "The Old Mill",
        "timezone": "Europe/London",
        "currency": "GBP",
        "locale": "en-GB"
    },
    "settings": {
        "venue": {
            "default_shelf": "A"
        },
        "session": {}
    }
}

Booking

common.schema.json#/$defs/booking

One booking as BookingNinja describes it to an app. It is sent inside context, in the bookings list of a blocks call, and returned by GET /bookings/{ref}.

Field Type Required Limits Description
ref string required pattern ^bkg_[a-z0-9]+$ Opaque booking reference, stable for the booking's life.
status string required one of draft, confirmed, cancelled, checked_in, completed, no_show Where the booking stands, worked out when the call is made. draft means the guest is still making it. confirmed is any other live booking. cancelled was cancelled, checked_in means the guest has arrived, completed means they have left, and no_show means they did not come.
session object required The session the booking is for.
session.id string required pattern ^ses_[a-z0-9]+$ Opaque session id. It is derived for each app, so a session has the same id every time for one app and a different id for any other.
session.name string required The session name as the venue calls it.
date string required format date Venue-local date.
start string required pattern ^[0-2][0-9]:[0-5][0-9]$ Venue-local wall-clock time, HH:MM.
end string required pattern ^[0-2][0-9]:[0-5][0-9]$ Venue-local wall-clock time the booking ends, HH:MM, worked out from its start and length. A booking that runs past midnight has an end earlier than its start.
party_size integer required at least 1 The number of guests in the booking.
tables array of string optional Names of the tables assigned to the booking, as the venue names them. Present on every booking that is not a draft, and an empty list until a table is assigned.
guest object optional The lead guest's contact details. Present only when the venue granted guests:read and the booking is not a draft. A detail the booking does not have is left out.
guest.name string optional The guest's name.
guest.email string optional The guest's email address.
guest.phone string optional The guest's phone number.
hold_id string or null optional The id the app gave, in its holds reply, to the hold it keeps for this booking. Null when the app holds nothing for it.
reservation_id string or null optional The id the app gave, in its holds/confirm reply, to the reservation it keeps for this booking. Null until the app has confirmed one.

Example

{
    "ref": "bkg_9f3c1a7e5b2d8046",
    "status": "confirmed",
    "session": {
        "id": "ses_4d8a2c6e1b73",
        "name": "Evening play"
    },
    "date": "2026-12-05",
    "start": "18:00",
    "end": "20:00",
    "party_size": 4,
    "tables": [
        "Table 12"
    ],
    "guest": {
        "name": "Alex Morgan",
        "email": "[email protected]",
        "phone": "+441632960123"
    },
    "reservation_id": "res_5521"
}

Field

common.schema.json#/$defs/field

One input. Used by app settings (manifest), guest fields blocks and staff action forms.

Field Type Required Limits Description
key string required pattern ^[a-z][a-z0-9_]{0,39}$ Identifier of the field. Its value is saved and sent back under this key.
type string required one of text, textarea, number, money, toggle, select, multiselect, info, date, time, email, phone, scale, consent How the input is drawn and what it sends. text, textarea, email and phone send a string; number, money (minor units) and scale send a number; toggle and consent send a boolean; select sends one option value; multiselect sends a list of them; date sends YYYY-MM-DD and time sends HH:MM, both venue-local; info shows text and sends nothing. A required consent must be true.
label string required at most 120 characters The text shown beside the field.
help string optional at most 300 characters A line of guidance shown under the field.
required boolean optional The field must be answered. For a consent that means ticked; a toggle is never required, since off is an answer.
default any optional The value the field starts with, of the type the field collects. For a setting it is also what the app receives until the venue saves a value.
min number optional number, money and scale only: the lowest value allowed. A scale without one starts at 1.
max number optional number, money and scale only: the highest value allowed. A scale without one ends at 5; a scale may have at most 20 steps.
max_length integer optional from 1 to 2000 The longest text allowed, for text and textarea fields. Without it a text field allows 255 characters and a textarea 2,000.
unit string optional at most 12 characters A short unit shown after the value, such as players.
options remote or array of option optional list: at most 200 items A fixed list, or the string remote to fetch choices from POST /settings/options (settings only).
url string optional format uri; pattern ^https://; at most 500 characters consent and info fields only: where the field's link goes. HTTPS only.
visible_when object optional Show this field only when another field in the same form has this value.
visible_when.key string required The key of the other field to look at.
visible_when.equals any required The value that other field must hold for this one to be shown. A hidden field is not required and its value is not kept.
display string optional one of dropdown, radio, checkboxes, pills select and multiselect only: how the choices are drawn. dropdown is the default; radio and checkboxes list every choice; pills is a compact row of buttons. radio and pills suit a select, checkboxes and pills a multiselect. A value that does not suit the field's type is ignored and the dropdown is used.
min_label string optional at most 40 characters scale only: the words under the lowest value, e.g. Never played.
max_label string optional at most 40 characters scale only: the words under the highest value, e.g. Play every week.
link_label string optional at most 60 characters consent and info only: the words of the link to url, e.g. Read the house rules.
placeholder string optional at most 80 characters Greyed example text inside an empty text, textarea, email, phone or number input.

Example

{
    "key": "default_shelf",
    "type": "text",
    "label": "Reserved game",
    "help": "Where the game is kept.",
    "required": true,
    "max_length": 200
}

Option

common.schema.json#/$defs/option

One choice in a select or multiselect field.

Field Type Required Limits Description
value string or number required What is saved and sent to the app when this choice is made.
label string required at most 120 characters What the person choosing sees.

Example

{
    "value": "a2",
    "label": "Reserved game"
}

Error reply

common.schema.json#/$defs/error

The body of every 4xx or 5xx reply. message may be shown to a guest or to staff. Use 422 with code invalid_request (or a more specific code) for a request the app cannot accept, 409 unavailable when an item has gone, and 404 not_found for an endpoint the app does not implement.

Field Type Required Limits Description
error object required The error itself.
error.code string required A short code in lower case with underscores, such as invalid_request or not_found. The codes BookingNinja itself returns are listed under each endpoint.
error.message string required at most 300 characters A plain sentence saying what went wrong, without internal detail.

Example

{
    "error": {
        "code": "unavailable",
        "message": "That game is no longer available."
    }
}

Manifest

manifest.schema.json

Field Type Required Limits Description
name string required at most 120 characters The app's name. Venues see it when they choose an app, and BookingNinja uses it to label the app's notes and actions in booking history.
description string optional at most 500 characters A sentence or two on what the app does, shown to venues beside its name.
icon_url string optional format uri; pattern ^https://; at most 500 characters HTTPS only. A square picture, PNG, JPEG or WebP, at least 256 pixels wide and up to 1 MB. BookingNinja fetches it once and serves its own copy.
listing object optional How the app is presented in BookingNinja's public app directory and on the venue's Apps page. Optional for an app only its developer's own venues use. Required before BookingNinja will list the app publicly: tagline, description, developer_name, privacy_url and one of support_url or support_email.
listing.tagline string optional at most 80 characters One line saying what the app does for a venue, shown under its name on directory cards.
listing.description string optional at most 2000 characters A fuller description for the app's own directory page. Plain text; blank lines separate paragraphs. No HTML or Markdown.
listing.developer_name string optional at most 80 characters The person or company that makes the app, shown as "By …".
listing.categories array of string optional at most 3 items; no repeats; each one of games, food_and_drink, entertainment, events_and_parties, equipment, loyalty_and_marketing, operations, accessibility, other Up to three categories the directory files the app under.
listing.screenshots array of object optional at most 6 items Up to six pictures of the app in use. BookingNinja fetches each once and serves its own copy, so a visitor's browser never contacts the app. PNG, JPEG or WebP, up to 2 MB each; 16:10 landscape shows best.
listing.screenshots[].url string required format uri; pattern ^https://; at most 500 characters Where BookingNinja fetches the picture from.
listing.screenshots[].caption string optional at most 80 characters A short line shown under the picture and read out as its description.
listing.website_url string optional format uri; pattern ^https://; at most 500 characters The app's own website.
listing.support_url string optional format uri; pattern ^https://; at most 500 characters Where a venue goes for help with the app.
listing.support_email string optional format email; at most 190 characters An address a venue can write to for help with the app. Shown publicly.
listing.privacy_url string optional format uri; pattern ^https://; at most 500 characters The app's privacy policy. Venues are shown this link on the consent screen and in the directory.
listing.terms_url string optional format uri; pattern ^https://; at most 500 characters The app's own terms of use, if it has any.
base_url string required format uri; pattern ^https://; at most 500 characters HTTPS. Every endpoint path is relative to this.
redirect_uri string required format uri; pattern ^https://; at most 500 characters Where BookingNinja sends the browser once a venue approves the connection, with a one-time code. It is also the value the token endpoint expects as redirect_uri when the code is exchanged.
install_url string optional format uri; pattern ^https://; at most 500 characters Optional, recommended. When a venue presses Connect, BookingNinja sends the browser here first with ?authorize_url=…, so the app can sign the venue in and create its own state. The app then redirects the browser to authorize_url with a state query parameter added (the URL already has a query string, so add it as a further parameter; 500 characters at most). BookingNinja returns that state unchanged on the callback to redirect_uri. Without install_url the callback carries no state, and the app must ask the signed-in user to confirm the link before attaching the installation to their account.
scopes array of string required no repeats; each one of bookings:read, bookings:write_notes, bookings:alert, guests:read What the app asks to do through BookingNinja's API: bookings:read reads the bookings the app is attached to, bookings:write_notes adds notes to them, bookings:alert sends alerts about them to the venue's staff and guests:read adds the guest's name and contact details. The venue sees these on the consent screen. A change that adds a scope does not widen a connection already made: the venue grants it when it reconnects.
extension_points object required Declare only the points the app uses.
extension_points.guest_step object optional Adds a step to the guest's booking flow, on each session where the venue switches it on.
extension_points.guest_step.default_label string required at most 40 characters The step's name in the booking flow. It is also the step's title when the guest-step reply gives none.
extension_points.guest_step.default_position string optional one of after_time Where the step sits in the booking flow. after_time, the only value, puts it after the guest has chosen the party size, date and time.
extension_points.booking_blocks object optional Shows the app's own badges, chips and blocks on bookings in the venue's admin.
extension_points.booking_blocks.slots array of string required no repeats; each one of gantt_bar, list_row, drawer The places the app shows blocks: gantt_bar is a badge on the booking in the Gantt chart, list_row is chips in the booking list and drawer is blocks in the booking's detail drawer.
extension_points.staff_actions boolean optional Whether the app's drawer blocks may include buttons for staff to press, which BookingNinja sends to POST /actions. Without it, actions blocks are dropped.
extension_points.guest_summary boolean optional Declares that the app returns a guest_summary from holds/confirm, to be shown to the guest on the confirmation page, in emails and on the manage-booking page.
extension_points.events array of string optional no repeats; each one of booking.confirmed, booking.updated, booking.cancelled, booking.checked_in, booking.completed, booking.no_show, installation.settings_updated, installation.uninstalled The event types the app wants sent to POST /events. An event type that is not listed is never sent.
extension_points.detail_panel object optional A page of the app's own that staff can open in a frame inside the booking drawer, for what blocks cannot show. It also needs the drawer slot in booking_blocks, and BookingNinja must have switched the panel on.
extension_points.detail_panel.url string required format uri; pattern ^https://; at most 500 characters The page to frame. BookingNinja opens it as {url}?token=<token> with a short-lived signed token. The page must allow itself to be shown in a frame.
catalogue object optional Describes the items the app offers, so BookingNinja can sync, search and filter them.
catalogue.attributes array of object optional at most 20 items The properties an item may carry, which collections can show on cards and filter or sort by. An attribute an item sends that is not declared here is dropped when the catalogue is synced.
catalogue.attributes[].key string required pattern ^[a-z][a-z0-9_]{0,39}$ Name of the attribute. It is the key used in an item's attributes and in filters, sorts and card text.
catalogue.attributes[].type string required one of number, enum, tags, text, boolean The kind of value: number, enum (one of options), tags (a list of short labels), text or boolean.
catalogue.attributes[].label string required at most 60 characters Name shown to guests and staff, for example beside a filter.
catalogue.attributes[].unit string optional at most 12 characters A short unit shown after a number, such as min.
catalogue.attributes[].options array of string optional at most 50 items For an enum attribute, the values an item may have. A value outside the list is dropped.
catalogue.sync boolean optional Set false when every collection is remote and the app does not implement POST /catalogue. Default true.
images object optional How item pictures reach the browsers of guests and staff.
images.delivery string optional one of cached, direct; default cached cached (default): BookingNinja fetches each item image once through its own servers and serves its own copy, so a guest's browser never contacts the app. direct: guest and staff browsers load image_url straight from the app's host (HTTPS only), which is faster for large or fast-changing libraries but shows the app each viewer's IP address; venues are told so on the consent screen.
settings object optional The settings a venue can set for the app. BookingNinja draws them as forms in the admin and sends the saved values to the app in context.settings.
settings.venue array of field optional at most 30 items Fields on the app's settings page that apply to the whole venue.
settings.session array of field optional at most 30 items Fields shown for each session the app is switched on for.

Example

{
    "name": "Catan",
    "description": "A game of trading and building for three or four players.",
    "icon_url": "https://apps.example.com/icon.png",
    "listing": {
        "tagline": "Tagline",
        "description": "A game of trading and building for three or four players.",
        "developer_name": "Developer name",
        "categories": [
            "games",
            "food_and_drink"
        ]
    },
    "base_url": "https://apps.example.com/bn",
    "redirect_uri": "https://apps.example.com/callback",
    "install_url": "https://apps.example.com/connect",
    "scopes": [
        "bookings:read",
        "bookings:write_notes"
    ],
    "extension_points": {
        "guest_step": {
            "default_label": "Choose a game",
            "default_position": "after_time"
        },
        "booking_blocks": {
            "slots": [
                "gantt_bar",
                "list_row"
            ]
        },
        "staff_actions": true,
        "guest_summary": true,
        "events": [
            "booking.confirmed",
            "booking.updated"
        ],
        "detail_panel": {
            "url": "https://apps.example.com/panel"
        }
    }
}

Guest step blocks

guest.schema.json#/$defs/guestBlock

One block of a guest step. collection, fields, options, quantities and plan collect something from the guest; the rest show information. BookingNinja draws every block in the venue's own branding and ignores block types it does not know.

Guest step blocks: type = collection

A list of items the guest can browse and choose from, taken from BookingNinja's copy of the catalogue or from the app live.

Field Type Required Limits Description
type string required always collection Always collection. It tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the block. Search and collection requests carry it as collection_id.
heading string optional at most 80 characters A heading shown above the list.
layout string optional one of grid, list, carousel; default grid How the items are laid out: as a grid of cards, as a vertical list or as a sideways carousel.
source string optional one of catalogue, remote; default catalogue catalogue (default): BookingNinja searches, filters, sorts and pages its synced copy of the catalogue. remote: the app does all of that itself. BookingNinja sends every change of search text, filter, sort or page to POST /collection and shows exactly what comes back, in the app's order, so results can be personalised, ranked, drawn from a catalogue too large or too changeable to sync, or carry live availability. A remote collection needs no catalogue sync. An app whose manifest sets catalogue.sync to false must make every collection remote.
item_ids array of string optional at most 100 items Show only these items, in this order. Omit to show the whole catalogue.
search object optional Settings for the search box above the list. A catalogue collection's text is always matched by BookingNinja on its synced copy; a remote collection's text is sent in query on POST /collection.
search.placeholder string optional at most 60 characters Hint text shown in the empty search box.
search.mode string optional one of local, remote Deprecated and ignored. To run search yourself, make the collection remote.
search.min_length integer optional from 0 to 10 Characters typed before a search is sent. Default 2.
filters array of object optional at most 8 items Initial filters. For a remote collection the app may replace them on any /collection response (for example to show result counts or narrow the choices).
filters[].id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the filter. The guest's choices are sent back keyed by this id.
filters[].label string required at most 40 characters The name of the filter, as the guest sees it.
filters[].type string required one of fits_range, max, min, one_of, any_of, toggle fits_range: the chosen number lies between min_key and max_key. max / min: the attribute is at most / at least the chosen number. one_of: the attribute equals the chosen option. any_of: a tags attribute contains any chosen option. toggle: an on/off switch sent as a boolean; remote collections only, since only the app knows what it means.
filters[].key string optional The item attribute the filter looks at, for max, min, one_of and any_of.
filters[].min_key string optional For fits_range: the attribute holding an item's lowest value, such as the fewest players.
filters[].max_key string optional For fits_range: the attribute holding an item's highest value, such as the most players.
filters[].choices array of number or string optional at most 30 items The values the guest can pick from, for max, min, one_of and any_of.
filters[].default any optional The value the filter starts on.
filters[].counts object optional Optional result count per choice, shown beside it. Keyed by the choice as a string.
filters[].counts.<key> integer optional at least 0 How many results have this choice.
sort array of object optional at most 6 items The sort options offered to the guest.
sort[].label string required at most 40 characters The name of the option, as the guest sees it.
sort[].key string required For a catalogue collection, name or a number attribute key. A remote collection may use any keys of its own, such as relevance.
sort[].direction string optional one of asc, desc; default asc Whether the sort runs from low to high (asc) or from high to low (desc).
card object optional How each item's card is drawn.
card.subtitle string optional at most 120 characters Text with {attribute_key} placeholders.
card.badges array of string optional at most 3 items Attribute keys shown as badges.
detail object optional What an item's detail view shows.
detail.show array of string optional at most 12 items description and attribute keys, in order.
page_size integer optional from 1 to 48 Items per page, 48 at most. Default 24.
empty_text string optional at most 160 characters Shown when there is nothing to list.
{
    "type": "collection",
    "id": "g_1042",
    "heading": "Choose a game",
    "layout": "grid",
    "source": "catalogue",
    "search": {
        "placeholder": "Search games",
        "mode": "local",
        "min_length": 2
    },
    "filters": [
        {
            "id": "players",
            "label": "Players",
            "type": "fits_range",
            "min_key": "players_min",
            "max_key": "players_max"
        }
    ],
    "sort": [
        {
            "label": "Name",
            "key": "name"
        }
    ],
    "card": {
        "subtitle": "{players_min} to {players_max} players",
        "badges": [
            "New"
        ]
    },
    "page_size": 24
}
Guest step blocks: type = fields

A small form the guest fills in on the step. The answers go to the app in answers on the holds request.

Field Type Required Limits Description
type string required always fields Always fields. It tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the block. A block with per_guest sends its answers under this id.
heading string optional at most 80 characters A heading shown above the form.
per_guest boolean optional default false Repeat the fields once per guest in the party.
fields array of field required 1 to 12 items The inputs in the form, in order.
{
    "type": "fields",
    "id": "g_1042",
    "heading": "Choose a game",
    "per_guest": false,
    "fields": [
        {
            "key": "shelf",
            "type": "text",
            "label": "Shelf",
            "help": "Where the game is kept.",
            "required": true,
            "max_length": 200
        }
    ]
}
Guest step blocks: type = options

A small fixed set of choices the guest picks from: packages, difficulty levels, room types, lanes, time slots within the visit. The answer is sent in answers under the block's id: one option id, or a list of them when multiple is true. Unlike a collection there is no search or paging; use it for up to 60 choices the app knows up front.

Field Type Required Limits Description
type string required always options Always options: it tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ The key the answer is sent under.
heading string optional at most 80 characters Shown above the choices.
help string optional at most 200 characters A line under the heading.
style string optional one of cards, tiles, list, pills, slots; default cards cards: picture, title, description and price, one or two per row. tiles: compact picture tiles. list: rows with a radio or tick. pills: a row of small buttons. slots: time-style buttons grouped under each option's group.
multiple boolean optional default false Let the guest pick more than one.
min integer optional at least 0 With multiple: the fewest the guest must pick.
max integer optional at least 1 With multiple: the most the guest may pick.
required boolean optional default false The guest cannot continue without choosing.
default any optional The option id chosen to begin with, or a list of ids when multiple is set. An unavailable or unknown id is ignored.
options array of object required 1 to 60 items The choices, in the order shown.
options[].id string required at most 64 characters Sent back as the answer. Unique within the block.
options[].title string required at most 80 characters The choice's name.
options[].description string optional at most 300 characters One or two sentences under the title.
options[].image_url string optional format uri; pattern ^https://; at most 500 characters A picture for card and tile styles. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
options[].price_hint string optional at most 30 characters Shown beside the choice, e.g. +£5. The price charged is always what the hold returns.
options[].badge string optional at most 24 characters A short label on the choice, e.g. Most popular.
options[].group string optional at most 60 characters slots style only: the heading this choice sits under, e.g. Morning.
options[].unavailable_label string optional at most 40 characters Set to show the choice greyed out and unselectable, e.g. Full.
{
    "type": "options",
    "id": "g_1042",
    "heading": "Choose a game",
    "help": "Where the game is kept.",
    "style": "cards",
    "multiple": false,
    "options": [
        {
            "id": "g_1042",
            "title": "Catan",
            "description": "A game of trading and building for three or four players.",
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "price_hint": "£3",
            "badge": "Badge"
        }
    ]
}
Guest step blocks: type = quantities

A list of things the guest sets a number for: shoe sizes, hire equipment, tokens, extras per head. The answer is sent in answers under the block's id as an object of row id to quantity; rows left at zero are left out.

Field Type Required Limits Description
type string required always quantities Always quantities: it tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ The key the answer is sent under.
heading string optional at most 80 characters Shown above the rows.
help string optional at most 200 characters A line under the heading.
total_min integer optional at least 0 The fewest the quantities must add up to.
total_max integer optional at least 1 The most the quantities may add up to. Use the party size to cap one-per-guest lists; the step is fetched again if the party size changes.
rows array of object required 1 to 40 items The rows, in the order shown.
rows[].id string required at most 64 characters The key this row's quantity is sent under.
rows[].label string required at most 80 characters What is being counted, e.g. Size 7 shoes.
rows[].description string optional at most 200 characters A line under the label.
rows[].image_url string optional format uri; pattern ^https://; at most 500 characters A small picture beside the row. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
rows[].price_hint string optional at most 30 characters Shown beside the row, e.g. £2 each.
rows[].min integer optional at least 0 The lowest quantity. Default 0. A row with a minimum above 0 always has at least that many and is always sent.
rows[].max integer optional from 1 to 999 The highest quantity. Default 20.
rows[].default integer optional at least 0 The quantity to begin with.
rows[].unavailable_label string optional at most 40 characters Set to show the row greyed out with its stepper disabled, e.g. None left.
{
    "type": "quantities",
    "id": "g_1042",
    "heading": "Choose a game",
    "help": "Where the game is kept.",
    "total_min": 0,
    "total_max": 1,
    "rows": [
        {
            "id": "g_1042",
            "label": "Shelf",
            "description": "A game of trading and building for three or four players.",
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "price_hint": "£3",
            "min": 1
        }
    ]
}
Guest step blocks: type = plan

A picture of a layout with places on it the guest can pick: lanes, pitches, karaoke rooms, desks, lockers, seats. The answer is sent in answers under the block's id: one spot id, or a list when multiple is true. Every spot is also listed as a button under the picture, so the block works without seeing or tapping the picture. Spots are rectangles or circles placed on the picture; a spot may not be rotated, so draw angled features into the picture and place an upright spot over each.

Field Type Required Limits Description
type string required always plan Always plan: it tells BookingNinja which kind of block this is.
id string required pattern ^[a-z][a-z0-9_]{0,39}$ The key the answer is sent under.
heading string optional at most 80 characters Shown above the plan.
help string optional at most 200 characters A line under the heading.
image_url string required format uri; pattern ^https://; at most 500 characters The plan itself. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
aspect_ratio number optional at most 10 The picture's width divided by its height, so space is reserved before it loads. Default 1.5.
multiple boolean optional default false Let the guest pick more than one spot.
min integer optional at least 0 With multiple: the fewest spots.
max integer optional at least 1 With multiple: the most spots.
required boolean optional default false The guest cannot continue without choosing.
spots array of object required 1 to 200 items The places on the plan.
spots[].id string required at most 64 characters Sent back as the answer.
spots[].label string required at most 40 characters The spot's name, e.g. Lane 4.
spots[].x number required from 0 to 100 Left edge, as a percentage of the picture's width.
spots[].y number required from 0 to 100 Top edge, as a percentage of the picture's height.
spots[].width number optional at most 100 Width as a percentage of the picture's width. Default 8.
spots[].height number optional at most 100 Height as a percentage of the picture's height. Default 8.
spots[].shape string optional one of rect, circle; default rect The outline drawn over the picture.
spots[].description string optional at most 200 characters Shown when the spot is chosen, e.g. Seats 6, next to the bar.
spots[].price_hint string optional at most 30 characters Shown with the spot, e.g. +£10.
spots[].unavailable_label string optional at most 40 characters Set to show the spot greyed out and unselectable, e.g. Taken.
{
    "type": "plan",
    "id": "g_1042",
    "heading": "Choose a game",
    "help": "Where the game is kept.",
    "image_url": "https://apps.example.com/images/g_1042.jpg",
    "aspect_ratio": 1,
    "multiple": false,
    "spots": [
        {
            "id": "g_1042",
            "label": "Reserved game",
            "x": 0,
            "y": 0,
            "width": 1,
            "height": 1,
            "shape": "rect",
            "description": "A game of trading and building for three or four players."
        }
    ]
}
Guest step blocks: type = notice

A short message shown on the step.

Field Type Required Limits Description
type string required always notice Always notice. It tells BookingNinja which kind of block this is.
text string required at most 300 characters The message.
tone string optional one of neutral, info, warning; default neutral How the message is coloured: plain, as information or as a warning.
{
    "type": "notice",
    "text": "Game reserved for this booking.",
    "tone": "neutral"
}
Guest step blocks: type = text

A heading or a paragraph of plain text on the step.

Field Type Required Limits Description
type string required always text Always text. It tells BookingNinja which kind of block this is.
text string required at most 600 characters The words to show.
style string optional one of heading, paragraph; default paragraph Whether the text is drawn as a heading or as a paragraph.
{
    "type": "text",
    "text": "Game reserved for this booking.",
    "style": "heading"
}
Guest step blocks: type = hero

A wide picture with a heading and a sentence, to open a step.

Field Type Required Limits Description
type string required always hero Always hero: it tells BookingNinja which kind of block this is.
image_url string required format uri; pattern ^https://; at most 500 characters The picture. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
alt string optional at most 160 characters What the picture shows.
heading string optional at most 80 characters Large words over or under the picture.
text string optional at most 300 characters A sentence under the heading.
{
    "type": "hero",
    "image_url": "https://apps.example.com/images/g_1042.jpg",
    "alt": "Alt",
    "heading": "Choose a game",
    "text": "Game reserved for this booking."
}

Pictures to look at: the room, the kit, the course. Nothing is chosen.

Field Type Required Limits Description
type string required always gallery Always gallery: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the pictures.
layout string optional one of carousel, grid; default carousel carousel: one row the guest swipes. grid: all pictures at once.
images array of object required 1 to 12 items The pictures, in order.
images[].image_url string required format uri; pattern ^https://; at most 500 characters The picture. HTTPS only. Shown through BookingNinja's own copy unless the app's manifest asks for direct image delivery.
images[].alt string optional at most 160 characters What the picture shows, for guests who cannot see it.
images[].caption string optional at most 160 characters A line under the picture.
{
    "type": "gallery",
    "heading": "Choose a game",
    "layout": "carousel",
    "images": [
        {
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "alt": "Alt",
            "caption": "Caption"
        }
    ]
}
Guest step blocks: type = steps

An ordered list of what will happen: an itinerary, how a session runs, what to do on arrival. Nothing is chosen.

Field Type Required Limits Description
type string required always steps Always steps: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the list.
items array of object required 1 to 12 items The steps, in order.
items[].title string required at most 80 characters What happens.
items[].text string optional at most 300 characters A sentence or two of detail.
items[].label string optional at most 24 characters A short marker beside the step, e.g. a time 18:00 or Step 1.
items[].icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
{
    "type": "steps",
    "heading": "Choose a game",
    "items": [
        {
            "title": "Catan",
            "text": "Game reserved for this booking.",
            "label": "Reserved game",
            "icon": "dice"
        }
    ]
}
Guest step blocks: type = details

Facts as label and value pairs: what is included, where to go, what was reserved.

Field Type Required Limits Description
type string required always details Always details: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the rows.
rows array of object required 1 to 12 items The pairs, in order.
rows[].label string required at most 60 characters What the fact is, e.g. Lane.
rows[].value string required at most 200 characters The fact itself, e.g. 4.
{
    "type": "details",
    "heading": "Choose a game",
    "rows": [
        {
            "label": "Shelf",
            "value": "A2"
        }
    ]
}
Guest step blocks: type = faq

Questions that open to show their answers: rules, what to bring, age limits.

Field Type Required Limits Description
type string required always faq Always faq: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the questions.
items array of object required 1 to 12 items The questions, in order. All start closed.
items[].question string required at most 160 characters The question.
items[].answer string required at most 1000 characters The answer, as plain text. Blank lines start a new paragraph.
{
    "type": "faq",
    "heading": "Choose a game",
    "items": [
        {
            "question": "Question",
            "answer": "Answer"
        }
    ]
}
Guest step blocks: type = table

A small table: a size chart, price tiers, a comparison. It scrolls sideways on a phone.

Field Type Required Limits Description
type string required always table Always table: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the table.
columns array of string required 1 to 6 items; each at most 40 characters The column headings.
rows array of array of string required 1 to 20 items; each at most 6 items The rows. Each is a list of cells, one per column.
highlight_row integer optional at least 0 The row to pick out, counted from 0, e.g. the one matching the guest's party size.
{
    "type": "table",
    "heading": "Choose a game",
    "columns": [
        "Columns"
    ],
    "rows": [
        [
            "Rows"
        ]
    ],
    "highlight_row": 0
}
Guest step blocks: type = meter

A bar showing how full something is: places left, level, progress.

Field Type Required Limits Description
type string required always meter Always meter: it tells BookingNinja which kind of block this is.
label string required at most 80 characters What is being measured, e.g. Places taken.
value number required at least 0 The amount so far.
max number required The amount that fills the bar.
caption string optional at most 120 characters Words under the bar, e.g. 3 of 8 places left.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "meter",
    "label": "Reserved game",
    "value": 0,
    "max": 4,
    "caption": "Caption",
    "tone": "neutral"
}

Links out to pages the app or venue hosts: house rules, a waiver, a how-to. Each opens in a new tab.

Field Type Required Limits Description
type string required always links Always links: it tells BookingNinja which kind of block this is.
heading string optional at most 80 characters Shown above the links.
links array of object required 1 to 6 items The links, in order.
links[].label string required at most 60 characters The words of the link.
links[].url string required format uri; pattern ^https://; at most 500 characters Where it goes. HTTPS only.
{
    "type": "links",
    "heading": "Choose a game",
    "links": [
        {
            "label": "Reserved game",
            "url": "https://apps.example.com/help"
        }
    ]
}
Guest step blocks: type = divider

A thin line and some space between groups of blocks.

Field Type Required Limits Description
type string required always divider Always divider: it tells BookingNinja which kind of block this is.
{
    "type": "divider"
}

Staff blocks

staff.schema.json#/$defs/staffBlock

Staff blocks: type = badge

A small coloured label, shown on a Gantt bar or in the drawer.

Field Type Required Limits Description
type string required always badge Always badge. It tells BookingNinja which kind of block this is.
label string required at most 24 characters The badge's text.
icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
tooltip string optional at most 160 characters Text shown when staff point at the badge.
{
    "type": "badge",
    "label": "Reserved game",
    "icon": "dice",
    "tone": "neutral",
    "tooltip": "A game is reserved for this booking."
}
Staff blocks: type = chip

A short pill of text, shown in a list row or in the drawer.

Field Type Required Limits Description
type string required always chip Always chip. It tells BookingNinja which kind of block this is.
label string required at most 30 characters The chip's text.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "chip",
    "label": "Reserved game",
    "tone": "neutral"
}
Staff blocks: type = text

A paragraph of plain text in the drawer.

Field Type Required Limits Description
type string required always text Always text. It tells BookingNinja which kind of block this is.
text string required at most 400 characters The words to show.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "text",
    "text": "Game reserved for this booking.",
    "tone": "neutral"
}
Staff blocks: type = key_value

A list of labelled values in the drawer, such as a shelf and a condition.

Field Type Required Limits Description
type string required always key_value Always key_value. It tells BookingNinja which kind of block this is.
rows array of object required at most 12 items The label and value pairs, in order.
rows[].label string required at most 40 characters What the value is.
rows[].value string required at most 160 characters The value.
{
    "type": "key_value",
    "rows": [
        {
            "label": "Shelf",
            "value": "A2"
        }
    ]
}
Staff blocks: type = image_list

A list of items with their pictures, in the drawer.

Field Type Required Limits Description
type string required always image_list Always image_list. It tells BookingNinja which kind of block this is.
items array of object required at most 10 items The entries, in order.
items[].item_id string optional A catalogue item whose image to show.
items[].title string required at most 160 characters The entry's main text.
items[].subtitle string optional at most 160 characters A second, smaller line of text.
{
    "type": "image_list",
    "items": [
        {
            "item_id": "g_1042",
            "title": "Catan",
            "subtitle": "3 to 4 players"
        }
    ]
}
Staff blocks: type = actions

Buttons staff can press. Each press sends POST /actions. Only shown when the manifest declares staff_actions.

Field Type Required Limits Description
type string required always actions Always actions. It tells BookingNinja which kind of block this is.
actions array of object required at most 5 items The buttons, in order.
actions[].id string required pattern ^[a-z][a-z0-9_]{0,39}$ Names the button and is sent back as action_id. It must be unique across the whole drawer, or the first button with the id wins.
actions[].label string required at most 30 characters The text on the button.
actions[].style string optional one of default, primary, danger; default default How the button looks: ordinary, emphasised or as a warning of something destructive.
actions[].confirm string optional at most 200 characters Ask staff to confirm with this wording first.
actions[].input string optional one of collection, fields collection: open the catalogue picker first. fields: open a small form first.
actions[].fields array of field optional at most 8 items The form's fields, for input of fields.
{
    "type": "actions",
    "actions": [
        {
            "id": "swap_game",
            "label": "Swap game",
            "style": "default",
            "confirm": "Remove this game from the booking?"
        }
    ]
}
Staff blocks: type = alert

A boxed message that stands out: something staff must do or know.

Field Type Required Limits Description
type string required always alert Always alert: it tells BookingNinja which kind of block this is.
title string optional at most 60 characters Bold first line.
text string required at most 400 characters The message.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "alert",
    "title": "Choose a game",
    "text": "Game reserved for this booking.",
    "tone": "neutral"
}
Staff blocks: type = stat

One figure shown large with a label: points balance, visits, minutes left.

Field Type Required Limits Description
type string required always stat Always stat: it tells BookingNinja which kind of block this is.
label string required at most 40 characters What the figure is.
value string required at most 40 characters The figure, as it should read, e.g. 320 or £12.50.
caption string optional at most 80 characters Small words under it.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
icon string optional one of dice, star, tag, clock, check, alert, gift, key, user, box, calendar, pin, ticket, heart, bolt, cup, music, trophy, shield, info, camera, leaf, flag, cart, wrench, sparkles A small glyph from BookingNinja's own icon set. An unknown name falls back to a neutral icon.
{
    "type": "stat",
    "label": "Reserved game",
    "value": "a2",
    "caption": "Caption",
    "tone": "neutral",
    "icon": "dice"
}
Staff blocks: type = meter

A bar showing how full something is.

Field Type Required Limits Description
type string required always meter Always meter: it tells BookingNinja which kind of block this is.
label string required at most 80 characters What is being measured.
value number required at least 0 The amount so far.
max number required The amount that fills the bar.
caption string optional at most 120 characters Words under the bar.
tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "meter",
    "label": "Reserved game",
    "value": 0,
    "max": 4,
    "caption": "Caption",
    "tone": "neutral"
}
Staff blocks: type = timeline

What has happened, newest first or oldest first as the app sends it: handed out, returned, checked.

Field Type Required Limits Description
type string required always timeline Always timeline: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
items array of object required 1 to 20 items The entries, in the order shown.
items[].title string required at most 80 characters What happened.
items[].text string optional at most 200 characters Detail.
items[].at string optional at most 24 characters When, as the app wants it to read, e.g. 18:02 or Tue 3 Dec.
items[].tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "timeline",
    "heading": "Choose a game",
    "items": [
        {
            "title": "Catan",
            "text": "Game reserved for this booking.",
            "at": "At",
            "tone": "neutral"
        }
    ]
}
Staff blocks: type = table

A small table.

Field Type Required Limits Description
type string required always table Always table: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the table.
columns array of string required 1 to 6 items; each at most 40 characters The column headings.
rows array of array of string required 1 to 20 items; each at most 6 items The rows. Each is a list of cells, one per column.
{
    "type": "table",
    "heading": "Choose a game",
    "columns": [
        "Columns"
    ],
    "rows": [
        [
            "Rows"
        ]
    ]
}
Staff blocks: type = tags

A row of small labels.

Field Type Required Limits Description
type string required always tags Always tags: it tells BookingNinja which kind of block this is.
tags array of object required 1 to 12 items The labels, in order.
tags[].label string required at most 30 characters The words.
tags[].tone string optional one of neutral, info, success, warning, danger How a block or message is coloured to show its weight: neutral for plain information, info for something worth noting, success for good news, warning for something that needs attention and danger for a problem.
{
    "type": "tags",
    "tags": [
        {
            "label": "Reserved game",
            "tone": "neutral"
        }
    ]
}
Staff blocks: type = people

People attached to the booking on the app's side: an instructor, a host, a guide.

Field Type Required Limits Description
type string required always people Always people: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
people array of object required 1 to 6 items The people, in order.
people[].name string required at most 80 characters Their name.
people[].role string optional at most 60 characters What they are doing, e.g. Instructor.
people[].note string optional at most 160 characters A line of detail.
people[].image_url string optional format uri; pattern ^https://; at most 500 characters A small photo. HTTPS only; shown through BookingNinja's own copy unless the manifest asks for direct delivery.
{
    "type": "people",
    "heading": "Choose a game",
    "people": [
        {
            "name": "Catan",
            "role": "Role",
            "note": "Reserved by phone.",
            "image_url": "https://apps.example.com/images/g_1042.jpg"
        }
    ]
}
Staff blocks: type = checklist

A list staff tick off: kit handed over, waiver seen, briefing done. Ticking a box that has an action_id presses that action with input.values set to {item, done}; a box without one is display only.

Field Type Required Limits Description
type string required always checklist Always checklist: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the list.
items array of object required 1 to 20 items The lines, in order.
items[].id string required at most 64 characters Sent as item when the box is ticked.
items[].label string required at most 120 characters What to check.
items[].done boolean required Whether it is ticked.
items[].action_id string optional pattern ^[a-z][a-z0-9_]{0,39}$ The action pressed when staff tick or untick the box. Use an id of its own, not one a button in this drawer already uses: a line that shares a button's id is shown as a read-only tick. BookingNinja treats the id as an action without a button, so the app must declare staff_actions.
{
    "type": "checklist",
    "heading": "Choose a game",
    "items": [
        {
            "id": "g_1042",
            "label": "Reserved game",
            "done": true,
            "action_id": "swap_game"
        }
    ]
}

Pictures staff may need: the item's condition, a photo taken at handover.

Field Type Required Limits Description
type string required always gallery Always gallery: it tells BookingNinja which kind of block this is.
heading string optional at most 60 characters Shown above the pictures.
images array of object required 1 to 8 items The pictures, in order.
images[].image_url string required format uri; pattern ^https://; at most 500 characters The picture. HTTPS only.
images[].alt string optional at most 160 characters What it shows.
images[].caption string optional at most 160 characters A line under it.
{
    "type": "gallery",
    "heading": "Choose a game",
    "images": [
        {
            "image_url": "https://apps.example.com/images/g_1042.jpg",
            "alt": "Alt",
            "caption": "Caption"
        }
    ]
}
Staff blocks: type = code

A code staff need: a locker number, a door code, a reference to quote.

Field Type Required Limits Description
type string required always code Always code: it tells BookingNinja which kind of block this is.
label string optional at most 60 characters What the code is for.
value string required at most 64 characters The code, shown large.
format string optional one of text, qr; default text text shows the characters; qr also draws a QR code.
caption string optional at most 120 characters A line under it.
{
    "type": "code",
    "label": "Reserved game",
    "value": "a2",
    "format": "text",
    "caption": "Caption"
}

Links out to the app's own pages for this booking. Each opens in a new tab.

Field Type Required Limits Description
type string required always links Always links: it tells BookingNinja which kind of block this is.
links array of object required 1 to 6 items The links, in order.
links[].label string required at most 60 characters The words of the link.
links[].url string required format uri; pattern ^https://; at most 500 characters Where it goes. HTTPS only.
{
    "type": "links",
    "links": [
        {
            "label": "Reserved game",
            "url": "https://apps.example.com/help"
        }
    ]
}