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.
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
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.
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.
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.
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.
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>">
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
In the BookingNinja admin, open Apps and choose Build your own app. Register your app with its manifest.
Connect the app to your own venue and try it on a test booking.
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.
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.
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 sourceremote, 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.
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.
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.
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 = collectionin 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).
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 = optionsin 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 = quantitiesin 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 = planin 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 = noticein 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 = textin 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 = heroin 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."
}
Reply: type = galleryin blocks[]
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.
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.
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.
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.
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.
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 = detailsin 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.
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.
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.
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.
{
"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.
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 = badgein 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 = chipin 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.
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_valuein 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.
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 = alertin 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 = statin 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.
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.
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 = tablein 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.
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.
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.
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.
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 = badgein 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 = chipin 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.
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_valuein 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.
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 = alertin 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 = statin 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.
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.
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 = tablein 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.
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.
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.
{
"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.
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.
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.
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.
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.
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.
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).
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."
}
Guest step blocks: type = gallery
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.
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.
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.
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.
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.
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.
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.
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.
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.