Developers
Build an app for BookingNinja
BookingNinja Apps lets an outside service plug into a venue's booking flow and admin over HTTP. Your app answers a few JSON requests and BookingNinja draws every screen, so you write no front-end code.
What an app can add
A step in the guest's booking
Show a choice or a form after the guest picks a time: a game to reserve, a lane, a package. Price it with lines that join the booking total.
Details and buttons for staff
Badges on the Gantt chart, chips in the booking list, and blocks and buttons in the booking drawer.
A summary for the guest
What was reserved, what happens on the day and a code to show. It appears on the confirmation page, in emails and on the manage-booking page.
Alerts for staff
Raise an alert on a booking. The venue chooses who is told, and how.
Its own settings in the venue's admin
Describe the settings in your manifest. BookingNinja draws the forms and sends the saved values with every call.
An app declares only the points it uses. A step is optional, and so is everything else.
How it works
-
1
Register
In the venue admin, open Settings, then Apps, then Build your own app. Paste your manifest. You get a client id, a client secret and a signing secret. They are shown once.
-
2
Build against your own venue
Connect your app to a venue you own, switch its step on for a session and make a test booking. The page lists the last 50 calls BookingNinja made to your app.
-
3
Submit for review
Send the app to us when it has answered a call from BookingNinja. BookingNinja staff review it. Until it is approved, only you can connect it, on venues you own.
-
4
Get listed
Once approved, any venue can connect your app. An app with a complete listing can also appear in the public directory.
Where to start
Read the guides in order, or jump to the one you need. The reference lists every endpoint with its fields and an example.
- Getting started From nothing to your step on a test booking. Register an app, write a manifest, connect it to your own venue and make a booking.
- Signatures and tokens How to check that a call really came from BookingNinja, how a venue connects your app, and how your app calls BookingNinja back.
- The guest step What your app shows the guest, how holds, confirms and releases work, how prices are set, and what happens when your app is slow or down.
- Staff blocks and alerts What your app shows staff on a booking, the buttons they can press, how to alert staff, how to leave a note, and how events reach your app.
- 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.
- 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.
- Testing A reference app to read, how to see what BookingNinja is doing to your app, a checklist to run before you submit, and the mistakes that come up most.
What we ask of an app
These are rules BookingNinja enforces or relies on. The guides explain each one.
- Answer inside the time limit for each call: 2 seconds for the guest step, 3 for holds, 5 for confirms. A slow app is skipped, and after repeated failures it is paused.
- Check the
X-BN-Signatureon every call and reject a timestamp more than 5 minutes from your clock. - Hold one thing at a time for a booking. A new hold with
replacesset supersedes the old one. - Reply 200 to a release even when the hold has already gone.
- Send a JSON object with every successful reply. An empty body counts as a failure.
- Use HTTPS on port 443 for every address you give us. BookingNinja refuses private addresses and does not follow redirects.
- Serve pictures over HTTPS. BookingNinja keeps its own copy by default, so guests never contact your server.
- Ask only for the scopes you use. A guest's name and contact details reach your app only if the venue grants
guests:read.