Use of this API requires a partner API Key. To obtain such a key, contact your Booxi representative.
*Note: the Partner API key should be used exclusively in server-side (backend) code to ensure it remains confidential.
Prior to use, consult Booxi's API fair use policy.
Remember that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting only.
API documentation links:
This article explains how to use the Booxi API to build an event calendar where your customers can select a group event on a specific date and book it.
Implementation
The implementation requires 3 simple steps:
Retrieve group events from one or several store locations.
Populate a calendar of your choice using the events retrieved in step 1.
Let the client book the selected event, either through the Booxi Booking Widget or directly through the API.
Retrieve Events
Group events scheduled in your Booxi calendar are retrieved via GET /groupEvent, using your merchant API Key.
This endpoint uses a public Merchant API Key, so it can safely be called from frontend code.
Request URL
https://api.booxi.com/booking/v1/groupEvent
cURL
curl -X 'GET' \
'https://api.booxi.com/booking/v1/groupEvent?from=2026-09-01T00%3A00%3A00Z&to=2026-09-04T00%3A00%3A00Z&offset=0&limit=20' \
-H 'accept: application/json' \
-H 'Booxi-APIKey: YOUR_MERCHANT_API_KEY'
The query minimally requires a from and to date (in UTC, RFC3339 format).
Optionally, you can filter results with:
keyword — a service booking tag (configured in the back office, under service details) associated with the events you want to retrieve.
serviceId — the ID of a specific store service. The service must belong to the store matching the Merchant API Key used in the request.
You can test this API here (North America):
If you need to display events from several store locations in the same calendar, repeat this same call once per store, using each store’s own Merchant API Key, then merge the results client-side.
Additional notes:
If you created content in multiple languages, set the language parameter to match your website.
For all queries, date ranges must not exceed 180 days.
Group events matching your query are returned in JSON format, sorted chronologically, with paging (if a cursor is returned, more results are available).
Here’s an example of a successful JSON response:
{
"offset": 0,
"limit": 20,
"total": 3,
"items": [
{
"id": 22597936,
"start": "2026-09-03T13:00:00Z",
"duration": 60,
"price": {
"visibility": "Show",
"amount": "0.00",
"amountPerPerson": "20.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "None"
},
"location": "Business",
"locationText": "",
"staffId": 74144,
"staffName": "Jim Smith",
"staffFirstName": "Jim",
"staffLastName": "Smith",
"serviceId": 197886,
"serviceName": "Group workshop",
"serviceCategoryId": 0,
"serviceCategoryName": "Main Services",
"attendeeCount": 0,
"attendeeCapacity": 100,
"isCompleted": false,
"onlineBookingAllowedFrom": "2025-09-03T04:00:00Z",
"onlineBookingAllowedUntil": "2026-09-03T13:00:00Z",
"createdOn": "2026-09-01T20:24:53Z"
},
{
"id": 22597940,
"start": "2026-09-03T14:00:00Z",
"duration": 60,
"price": {
"visibility": "Show",
"amount": "0.00",
"amountPerPerson": "20.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "None"
},
"location": "Business",
"locationText": "",
"staffId": 74144,
"staffName": "Jim Smith",
"staffFirstName": "Jim",
"staffLastName": "Smith",
"serviceId": 197886,
"serviceName": "Group workshop",
"serviceCategoryId": 0,
"serviceCategoryName": "Main Services",
"attendeeCount": 0,
"attendeeCapacity": 100,
"isCompleted": false,
"onlineBookingAllowedFrom": "2025-09-03T04:00:00Z",
"onlineBookingAllowedUntil": "2026-09-03T14:00:00Z",
"createdOn": "2026-09-01T20:25:00Z"
},
{
"id": 22597941,
"start": "2026-09-03T15:00:00Z",
"duration": 60,
"price": {
"visibility": "Show",
"amount": "0.00",
"amountPerPerson": "20.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "None"
},
"location": "Business",
"locationText": "",
"staffId": 74144,
"staffName": "Jim Smith",
"staffFirstName": "Jim",
"staffLastName": "Smith",
"serviceId": 197886,
"serviceName": "Group workshop",
"serviceCategoryId": 0,
"serviceCategoryName": "Main Services",
"attendeeCount": 0,
"attendeeCapacity": 100,
"isCompleted": false,
"onlineBookingAllowedFrom": "2025-09-03T04:00:00Z",
"onlineBookingAllowedUntil": "2026-09-03T15:00:00Z",
"createdOn": "2026-09-01T20:25:02Z"
}
]
}Retrieve a Single Event’s Details
Once an event has been selected — for example, if you’re refreshing an event page or reloading state after a deep link — you can retrieve its full details directly with GET /groupEvent/{id}:
Add Events to Your Calendar
With the data returned by GET /groupEvent, you can populate the calendar UI of your choice. For each event, keep track of its id — you’ll need it later to open the booking flow.
Here are the properties of an event you can use:
Property | Description | Example |
id | ID associated with a group event. Required to book the event. | “id”: 1 |
start | The event’s starting date/time in RFC3339 format. Adjust it to the browser’s local timezone for display. | “start”: “2022-06-30T09:00:00Z” |
duration | The event’s duration in minutes. | “duration”: 30 |
price | A multi-field object describing an event’s price. | “price”: {“visibility”: “Show”, “amount”: “10.00”, “amountPerPerson”: “5.00”, “amountPerHour”: “0.00”, “currency”: “USD”, “isStartingAt”: false, “tax”: “Excluded”} |
staffId | ID associated with the staff providing the service. | “staffId”: 1 |
staffName | The staff’s full name. | “staffName”: “string” |
serviceId | ID of the service to be provided. | “serviceId”: 1 |
serviceName | The service’s name. | “serviceName”: “Custom Service” |
serviceCategoryId / serviceCategoryName | Category ID and name associated with a service. Can be used to filter content in the calendar. | “serviceCategoryId”: 0, “serviceCategoryName”: “VIP” |
location | Where the service is provided: “Business”, “Custom”, “Home”, “Phone”, or “VideoConference”. | “location”: “Business” |
profileImageUrl | Image associated with the service. | “profileImageUrl”: “https://…” |
description | The service’s description. | “description”: “…” |
attendeeCount / attendeeCapacity | The event’s attendance and capacity. Can be used to display how many spots are still available. | “attendeeCount”: 3, “attendeeCapacity”: 8 |
In most cases, displaying the event’s name and duration in the calendar will suffice. The remaining data can be shown in an overlay or a dedicated event page, where additional details and functionality — such as selecting other dates or times for the same event — could be added.
Booking the Event
Once a client selects an event, you have two options to let them book it: open the Booxi Booking Widget, or book the reservation directly through the API from your own backend.
Option A — Open the Booking Widget
Use any UI element of your choice to display the event’s details along with a “Book Now” button. Map the button’s onclick event to a call to BookNow.open(), passing your Merchant API Key along with the event’s serviceId and groupEventId:
<button class="code-booknow-button"
onclick="BookNow.open({apiKey:'YOUR_MERCHANT_API_KEY', serviceId:'12345', groupEventId:'200012345'})">Book Now</button>
Once clicked, the booking widget opens pre-loaded with that event.
Option B — Book Directly Through the API
If you’d rather build your own booking UI instead of using the Booxi Booking Widget, you can create the reservation directly with POST /booking, using your Partner API Key from your backend (never expose this key in frontend code).
Set bookingMethod to "GroupReservation" and pass the groupEventId you retrieved earlier, along with the client and attendee details:
{
"merchantId": 1002,
"bookingMethod": "GroupReservation",
"groupEventId": 213,
"client": {
"firstName": "Emilie",
"lastName": "Authier",
"email": "emilie.authier@booxi.com",
"homePhoneNumber": "",
"mobilePhoneNumber": "",
"remindByEmail": true,
"remindBySMS": false,
"additionalRequest": "Can we bring our own ingredients?",
"isAttending": true
},
"attendees": [
{
"firstName": "Emilie",
"lastName": "Authier",
"email": "emilie.authier@booxi.com",
"homePhoneNumber": "",
"mobilePhoneNumber": "",
"remindByEmail": true,
"remindBySMS": false,
"isRequester": true
}
],
"clientCommunication": "ClientAndAttendees",
"createdBy": "Client"
}
Additional Options
Filtering Content by Store, Service, or Service Category
Providing your clients the ability to filter your calendar’s content by store, service, or category creates a better user experience. The API provides methods to retrieve this information, which can be used to populate dropdown menus, lists, or any other UI element. Using GET /service, you can obtain the list of services offered by a merchant. When a service is selected, filter the calendar’s content by matching the selected serviceId.
If your calendar displays events for multiple stores, note that service IDs differ per store. If you want to filter by service across multiple locations, consider using the service tag instead. If all stores offer the same services, list the services of one store and use the service tag with the API’s keyword parameter. Another option is to hardcode filter categories mapped to service tags.
Reference
Your Merchant API key can be found in the Back Office, under My Business > Business Details.
Partner API keys are not publicly available; contact your Booxi representative to obtain one. The Partner API key must only be used in server-side (backend) code to keep it secret.