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.

json
{
  "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.venue applies to the whole venue. The venue fills it in on your app's page, under Settings, then Apps.
  • settings.session is 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) and placeholder (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.
  • min and max for numbers, money and scales. A scale may have at most 20 steps. min_label and max_label put words under its ends.
  • max_length for text, up to 2,000. Without it a text field allows 255 characters and a textarea 2,000.
  • unit, such as players, shown after the value.
  • url and link_label for a consent or an info field. The link must be HTTPS.
  • display for a select or multiselect: dropdown (the default), radio, checkboxes or pills. A value that does not suit the type is ignored.
  • options: a fixed list of {value, label} choices, up to 200, or the text remote (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. The key it 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:

json
{
  "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:

json
{ "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.

json
{
  "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.

json
{
  "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_cursor must 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:

json
{ "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.