Developers
Review and listing
How an app goes from draft to approved, what a change after approval costs you, and what a public directory listing needs.
Who can connect your app
Anyone with a BookingNinja account can register an app and test it. Until BookingNinja approves it, only you can connect it, and only on a venue you own. Being on a venue's team, having a partner grant or sharing a login does not count: the venue's owner must be you.
Once an app is approved, any venue can connect it.
The stages
| Status | What it means | What you can do |
|---|---|---|
| Draft | You are building. A change to the manifest applies at once. | Edit, connect to your own venue, send for review, delete (if no venue is connected) |
| In review | BookingNinja staff are looking at it. | Withdraw it. If you edit it, it goes back to draft. |
| Approved | Any venue can connect it. | Edit (an edit waits for review, see below) |
| Suspended | BookingNinja has switched it off. | Rotate secrets. Contact us. |
Sending a draft for review
Choose Send for review on your app. BookingNinja refuses until:
- Every address in the manifest is HTTPS.
- Your app is connected to one of your venues.
- Your app has answered at least one call from BookingNinja, successfully, in the last 14 days.
You can send an app for review up to 10 times an hour.
What happens in review
BookingNinja staff see what your manifest asks for: the scopes with the wording a venue will see, the extension points, the events, the addresses and whether pictures are delivered directly from your host. For an app that venues already use, they also see how your app has been answering: how many calls, and how long the median reply took, over the last 24 hours.
BookingNinja has not published written review criteria yet. This guide only describes what the review shows, and the rules that apply after it.
A reviewer can approve the app, or send it back with a reason. A rejected app goes back to draft, and the reason shows on your app as "Note from our review". Fix what it says and send it again.
Changing an approved app
Every change to an approved app's manifest goes to review again. There is no list of small changes that skip it: a new setting, a changed label and a new scope all wait.
When you save, your app shows "Changes waiting for review". Venues keep using the approved version until BookingNinja approves the change. If you save the approved version again, the waiting change clears. Choose Discard changes to drop it.
Because a waiting change is not live, you cannot test it on your own venue. To try a big change, register a second draft app and test there.
Some changes do more than wait:
- A new scope. Approving a change that adds a scope does not widen a venue's existing connection. Each venue gets the new scope only when it connects again.
- A new address. If
base_url,redirect_uri,install_urlor the framed panel's address moves to another origin (a different scheme, host or port), approving it pauses every venue that is connected to your app, except the ones you own. Each shows your app as "Needs connecting again" and has to connect again. Its tokens stop working. Its settings and the sessions it was switched on for stay. - An address you add on the old origin does not count as a move, and nor does removing one.
BookingNinja can also suspend an app at any time. A suspended app is switched off for every venue, and you cannot change it. If BookingNinja unsuspends an app that was approved before, it goes back to approved. Otherwise it goes back to draft.
What approval changes
An approved app gets fuller limits. Until then, a catalogue sync fetches 20 pages instead of 200, and the picture and storage budgets are a tenth of the full ones. At most one sync and one picture fetch for all of a developer's unapproved apps run at a time.
Limits on registering
- You can hold up to 25 apps. An app you deleted in the last 30 days still counts.
- You can register 10 apps an hour and rotate secrets 20 times an hour.
- A manifest is up to 64 KB. Every address in it is up to 500 characters.
The directory listing
BookingNinja keeps a public directory of apps. An app can be in it only if it is approved, has a complete listing, and BookingNinja staff list it. Approval does not list an app by itself.
You describe the listing in the manifest, under listing, and set icon_url:
{
"name": "Package Picker",
"description": "Lets guests choose a package for their visit.",
"icon_url": "https://picker.example.com/icon.png",
"base_url": "https://picker.example.com",
"redirect_uri": "https://picker.example.com/connected",
"scopes": [],
"extension_points": { "guest_step": { "default_label": "Choose a package" } },
"listing": {
"tagline": "Let guests pick a package when they book.",
"description": "Package Picker adds a step to your booking flow where guests choose a package for their visit.\n\nYou set the prices on each session.",
"developer_name": "Example Apps Ltd",
"categories": ["events_and_parties"],
"screenshots": [
{ "url": "https://picker.example.com/shots/step.png", "caption": "The step on a phone" }
],
"website_url": "https://picker.example.com",
"support_email": "[email protected]",
"privacy_url": "https://picker.example.com/privacy"
}
}
What a listing needs
For BookingNinja to list your app, these must be set:
tagline: one line, up to 80 characters, saying what the app does for a venue. It shows under your app's name on directory cards.description: up to 2,000 characters, in plain text. Blank lines separate paragraphs. HTML and Markdown are not read.developer_name: up to 80 characters. It shows as "By …".privacy_url: your privacy policy. Venues are shown this link on the consent screen and in the directory.- One of
support_urlorsupport_email. A support email is shown publicly. - An
icon_url.
The rest is optional:
categories: up to three ofgames,food_and_drink,entertainment,events_and_parties,equipment,loyalty_and_marketing,operations,accessibilityandother.screenshots: up to six, each with aurland acaptionof up to 80 characters.website_urlandterms_url.
A listing is optional for an app that only your own venues use.
Pictures
- Icon. HTTPS, square, PNG, JPEG or WebP, at least 256 pixels wide and up to 1 MB.
- Screenshots. HTTPS, PNG, JPEG or WebP, up to 2 MB each. A 16:10 landscape shape shows best.
- Never SVG. BookingNinja does not accept it.
BookingNinja fetches each picture once and serves its own copy, so a visitor's browser never contacts your server. If a picture fails to copy, BookingNinja keeps the copy it had. The icon is copied before your app can be listed.
A listing change is a manifest change
Editing the listing or the icon of an approved app goes to review like any other change. A reviewer sees it as "Directory listing changed".
If your app leaves approved
Suspending an app, or any other move away from approved, removes it from the directory. Unsuspending does not list it again.
How a venue connects from the directory
A directory page has a Connect link. It takes a venue to its own Apps page with your app selected, after signing in if it has to. Nothing connects by itself. The venue presses Connect and sees the consent screen, with the scopes your app asks for in plain words, your privacy link, and a notice if you chose direct picture delivery. When it approves, your callback runs as in Signatures and tokens.
The directory shows how many venues have connected your app only once it is five or more.
See what a listing looks like in the app directory.