Bookings

Bookings API

A public, server-to-server API for selling Experience bookings directly from your own website or e-commerce store. Build the booking journey in your own branding and design instead of linking guests out to an Embed front end while Embed keeps experiences, availability, and payments in sync.

BETA

API Endpoints

The BOOKINGS E-Commerce API is a public-facing, server-to-server API that lets you add Experience bookings to your own website, e-commerce platform or app. The goal is to give integrators full control over the guest experience: rather than sending customers to an Embed-hosted booking page, you build the browsing, selection, and checkout flow in your own style and brand, and use this API to read live experiences and availability, hold and confirm bookings, and record payment. Embed remains the source of truth for experiences, session capacity, and order state.

What You Can Build

A branded "Book an Experience" section on your own website or online store
Location and the available experiences listings pulled live from Embed
A date and time-slot picker driven by real session availability
A custom checkout that reserves a slot, captures guest details, and takes payment through your own payment provider
Order confirmation and cancellation handling within your own account or booking-management screens
Back-office sales reporting for the experiences you sell online

How It Fits Together

You own the front end. The look, feel, and journey are entirely yours — this API only supplies the data and booking operations.
Server-to-server. Calls are made from your backend using a client secret, not from the browser.
Embed stays authoritative. Availability, capacity, and order status are always validated against the Embed platform to prevent overbooking.

Key Concepts and Terminology

Term	Description
Operator / Customer	The business entity that Embed provides systems and services to (e.g. a Family Entertainment Centre).
Location	The physical venue where all of the fun occurs.
Guest	The end user — the Operator's customer who plays games and uses the wallet.
TOOLKIT	Embed's on-premise platform of software and services used to manage and operate a location.
Experience	The term used in BOOKINGS to cover any type of bookable activity, game or ride.
Session	These are specific time slots associated with experiences where guests will book the time that they wish for an experience.
General Admission	This relates to experience types that do not have a specific time to attend. They might be used to sell an entry ticket online.

The BOOKINGS E-Commerce API is a REST based interface that allows an integrator to utilise online functionality of the overall BOOKINGS system.

BOOKINGS technology comprises of the following components:

Layer	Component	Role
Cloud	TOOLKIT Portal	The cloud based configuration app where experiences, sessions, tickets etc are configured.
Cloud	E-Commerce	The online display and sales of experiences, including a front end and back end that this API is connected to.
On-Premise	TOOLKIT	The main location based backend software responsible for running operations and in this context syncs the BOOKINGS product information and availability from/to the cloud.
On-Premise	SALES	Staff facing application that includes ability to sell and manage experience bookings.
On-Premise	KIOSK+	Guest facing self service kiosk and app that includes ability to sell experience bookings.

Prerequisites

TOOLKIT must be installed in all venues where experiences are to be sold. The minimum TOOLKIT version is Inf-2026.1.0.EAP0.
A BOOKINGS subscription is required as well as the solution deployed and client secret generated by Embed.
To make any API calls, an Experience must be created with its associated tickets and sessions.
A Windcave account will be required to allow you to integrate with their payment gateway.

Key Characteristics

Feature	Details
Protocol	HTTPS only
Architecture	Cloud based RESTful, server-to-server (backend-to-backend only)
Authentication	Bearer token — exchange your client secret at `POST /api/v1/token`
Token Lifetime	6 hours — request a new token when it expires
Data Format	JSON request and response bodies

Typical Booking Flow

Call the endpoints in this order to complete a booking from your own storefront:

1. Authenticate
2. Get locations
3. Get experiences
4. Get session slots
5. Check availability
6. Reserve a slot
7. Create the order
8. Finalise sale / Record payment

See the API Endpoints reference for the full request and response details, including field-level information and example payloads for every endpoint.

The Bookings API uses Bearer Authentication with JWT (JSON Web Tokens). Every API request must include a valid access token in the Authorization header:

Authorization: Bearer <access_token>

Step 1 — Get Your Client Secret

The Client Secret is provisioned by Embed as part of the Bookings API setup. It is available in TOOLKIT Portal once your account has been configured.

Log in to TOOLKIT Portal at https://toolkit.helixleisure.net
Navigate to API Integration in the left-hand menu
Locate the BOOKINGS module row
Click Show Key to reveal the Client Secret value
Copy the key for use in your server-side environment

🔒 Security: Never store the Client Secret in your application source code or a client-side environment. Store it securely server-side — for example in an environment variable, a secrets manager, or a vault service. Do not commit it to version control.

Step 2 — Get a Bearer Token

Obtain an access token by calling POST /api/v1/token with your client secret
Include the token in all subsequent requests as: Authorization: Bearer {access_token}
Tokens are valid for 6 hours — request a new token when expired

Error Reference

HTTP Status	Likely Cause	Recommended Action
400 Bad Request	Malformed request body or missing required fields	Check field names, types, and that all required fields are present
401 Unauthorized	Missing, expired, or invalid Bearer token	Obtain a fresh token via `/api/v1/token` (admin) or `/api/v1/admin/token` (guest refresh)
403 Forbidden	Using the wrong token type for the endpoint	Ensure admin token is used for sign-up/login, Cognito token for guest operations
404 Not Found	Guest account or card not found	Verify the email address or card details are correct
409 Conflict	Username already exists	Use a different email address or check if the guest is already registered
422 Unprocessable Entity	Password does not meet rules, or card is not activated	Check password rules; ensure the game card has been activated in-store
500 Internal Server Error	Server-side error	Retry the request; if the issue persists, contact Embed support