Developers
Settings and catalogue
Let venues set up your app from their own admin, and give BookingNinja a catalogue of your items to search, filter and show.
Settings
A venue sets your app up in its own admin. You describe the settings in the manifest and BookingNinja draws the forms, saves the values and sends them to your app. You write no settings page.
{
"name": "Package Picker",
"base_url": "https://picker.example.com",
"redirect_uri": "https://picker.example.com/connected",
"scopes": [],
"extension_points": { "guest_step": { "default_label": "Choose a package" } },
"settings": {
"venue": [
{ "key": "plus_limit", "type": "number", "label": "Plus packages for each time", "min": 1, "max": 10, "default": 1 },
{ "key": "terms", "type": "consent", "label": "I accept the terms", "url": "https://picker.example.com/terms", "link_label": "Read the terms", "required": true }
],
"session": [
{ "key": "plus_price", "type": "money", "label": "Price of the Plus package", "default": 500, "help": "In the smallest unit of your currency. Leave at 0 to include it." }
]
}
}
There are two levels:
settings.venueapplies to the whole venue. The venue fills it in on your app's page, under Settings, then Apps.settings.sessionis filled in for each session the venue switches your app on for, in the session editor's Apps tab.
Each level holds up to 30 fields, and a key can be used once in a level.
Field types
A field has a key, a type and a label. The key is used to save the value and to send it back to you, and matches [a-z][a-z0-9_]{0,39}. The type decides how the field is drawn and what it sends.
| Field type | What the venue sees | What your app receives |
|---|---|---|
text |
A single line | A string |
textarea |
Several lines | A string |
email |
An email address | A string |
phone |
A phone number | A string |
number |
A number | A number |
money |
An amount | A number, in minor units (300 is 3.00) |
scale |
A row of steps, from 1 to 5 unless min and max say otherwise |
A number |
toggle |
An on or off switch | True or false |
consent |
A tick box with a link, such as "I accept the terms" | True or false |
select |
One choice | The chosen option's value |
multiselect |
Several choices | A list of values |
date |
A date | YYYY-MM-DD, in the venue's time zone |
time |
A time | HH:MM, in the venue's time zone |
info |
Text, and a link if you give a url |
Nothing |
A field can also carry:
label(up to 120 characters),help(up to 300) andplaceholder(up to 80).required. For a consent it means ticked. A toggle is never required, because off is an answer.default. It is what your app receives until the venue saves a value.minandmaxfor numbers, money and scales. A scale may have at most 20 steps.min_labelandmax_labelput words under its ends.max_lengthfor text, up to 2,000. Without it atextfield allows 255 characters and atextarea2,000.unit, such asplayers, shown after the value.urlandlink_labelfor a consent or an info field. The link must be HTTPS.displayfor aselectormultiselect:dropdown(the default),radio,checkboxesorpills. A value that does not suit the type is ignored.options: a fixed list of{value, label}choices, up to 200, or the textremote(below).visible_when: show the field only when another field in the same form has a given value. A hidden field is not required and its value is not kept. Thekeyit names must be another field in the same list.
The same field definition is used for the fields of a fields block on the guest step and the form of a staff button.
How your app receives them
Every call carries the saved values in context.settings.venue and context.settings.session. A setting the venue has not saved carries its manifest default. The session object is empty when a call is not about one session. An info field sends nothing.
Choices your app supplies
For a select or multiselect whose options is remote, BookingNinja asks your app for the choices when the form opens. It calls POST /settings/options:
{
"options": [
{ "value": "lib_main", "label": "Main library" },
{ "value": "lib_family", "label": "Family library" }
]
}
The request carries the level (venue or session), the field's key and values, the form's current values that are not saved yet, so a list can depend on another field. Reply with up to 200 choices. If your app fails, the field shows no choices.
Checking a save
When a venue saves, BookingNinja checks the values against your field definitions first: required fields, ranges, lengths and formats. It then calls POST /settings/validate with the level and the values it is about to store. Reply 200 to accept the save. To refuse it, reply 422 with a message for each field:
{ "errors": { "plus_limit": "You can offer 4 Plus packages at most with this size of table." } }
The venue sees each message beside its field. A message for a key that is not a field is shown with the form instead, and each message is cut to 300 characters.
A 404, a timeout, a pause or any other reply lets the save through. Your app never stops a venue from saving by being slow or down.
After a save that changed something, BookingNinja sends installation.settings_updated if you listed it in events. A change to the venue's settings also starts a catalogue sync.
The catalogue
A catalogue is the list of items your app offers: games, rooms, add-ons. BookingNinja keeps its own copy, so it can search, filter, sort and show items quickly, without a call to your app for each key press, and while your app is slow.
You need a catalogue if a collection block has source catalogue (the default). You do not need one if every collection is remote. In that case set catalogue.sync to false in your manifest, and BookingNinja never asks.
What your app declares
The manifest's catalogue.attributes lists the properties an item may have, which collections can show on cards and filter or sort by. An item that sends an attribute you have not declared loses it when it is synced.
{
"name": "Package Picker",
"base_url": "https://picker.example.com",
"redirect_uri": "https://picker.example.com/connected",
"scopes": [],
"extension_points": {},
"catalogue": {
"attributes": [
{ "key": "min_players", "type": "number", "label": "Min players" },
{ "key": "play_minutes", "type": "number", "label": "Play time", "unit": "min" },
{ "key": "complexity", "type": "enum", "label": "Complexity", "options": ["light", "medium", "heavy"] },
{ "key": "categories", "type": "tags", "label": "Categories" }
]
}
}
An attribute's type is number, enum (one of its options), tags (a list of short labels), text or boolean. You can declare up to 20.
What your app answers
BookingNinja calls POST /catalogue with a cursor that is empty for the first page. Reply with a page of items, and a next_cursor for the next page, or none on the last page.
{
"items": [
{
"id": "g_0042",
"name": "Catan",
"summary": "Trade, build and settle.",
"description": "Players collect and trade resources to build roads and settlements.",
"image_url": "https://picker.example.com/images/g_0042.jpg",
"attributes": { "min_players": 3, "play_minutes": 75, "complexity": "medium", "categories": ["strategy", "trading"] },
"updated_at": "2026-11-01T09:30:00Z",
"rating": { "value": 4.5, "count": 128 }
}
],
"next_cursor": "page-2"
}
An item is a title, not a physical copy. Its id is up to 64 characters and is compared exactly, so abc and ABC are two items. An item's name is up to 160 characters, summary 200 and description 4,000. Send updated_at so BookingNinja knows when to fetch a picture again.
The limits of one sync:
- A page holds up to 500 items.
- A sync takes up to 200 pages, and up to 20,000 items in all. An app that BookingNinja has not approved yet gets 20 pages.
- The whole run has 120 seconds. One page that takes longer than 0.8 times the 30 second page timeout ends the run early.
next_cursormust change from page to page, or the sync stops.
A sync that goes over a limit, or fails, is thrown away and BookingNinja keeps the copy it had. A slow page does not pause your app.
When it runs
BookingNinja syncs when your app is connected, when the venue saves its settings, once a day, and when your app asks. To ask, call POST /api/v1/apps/catalogue/changed with your token. BookingNinja starts a sync, at most one a minute for each installation. A call within that minute is still answered 202, and is not queued again.
Until a developer's apps are approved, at most one sync of any of their apps runs at a time.
Pictures
Cached, the default
For an item's image_url, and for the pictures in blocks such as hero, gallery and plan, BookingNinja fetches each picture once, on a background queue, and serves its own copy. A guest's browser never contacts your server.
- The first view may show a placeholder. A guest's request never fetches a picture. If BookingNinja has no copy yet, it fetches one in the background and shows the picture on the next view.
- Limits. A picture is up to 2 MB and its type is checked. SVG is not accepted in production. BookingNinja fetches it with a short timeout and only from a public HTTPS address.
- A budget for each installation. BookingNinja stores up to 5000 pictures, queues up to 600 fetches an hour, and caps their total size. An app that has not been approved gets a tenth of each. Past a limit, a picture is not stored.
- Remote collections. A remote item is stored for names and pictures elsewhere, up to 5000 of them. Past that, new items still show from your live answer, but without a stored name or picture elsewhere.
- Emails. Emails never load a picture from your server. They show BookingNinja's copy, or none.
Direct
If your library is large or changes fast, you can ask for pictures to be served from your own server:
{ "images": { "delivery": "direct" } }
Guests' and staff's browsers then load image_url straight from your host, which is faster. It also means your server sees each viewer's IP address and when they looked. Venues are told so on the consent screen, and reviewers see it too. Your pictures must be HTTPS.
BookingNinja can switch off direct delivery for every app, and then always serves a cached copy. Do not build on the assumption that your host sees each view.