Use of this API requires a partner API Key. To obtain such a key, contact your Booxi representative.
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 an event on a specific date, and book it.
Implementation
The implementation requires 3 simple steps:
Retrieve events from one or several store locations.
Populate a calendar using the events retrieved in step 1.
Launch Book Now for a specific event when selected.
Before proceeding, it is assumed that a calendar solution has already been integrated to your website. All examples included in this article make use of fullCalendar.io. If your website uses a different technology, fullCalendar’s methods can be replaced with any other solution’s equivalents.
Retrieve Events
Group events scheduled in your Booxi calendar can be retrieved via API, which is required prior to populating your calendar widget.
Events for a single store location can be retrieved by sending a query to the API with GET /groupEvent using your merchant API Key. The query minimally requires a start and end dates (in Zero timezone RFC3339 format). Optionally, you can provide a serviceKeyword (tag) or store service ID for events associated with a service booking tag (in the back office service details), or id.
Request URL
cURL
curl -X GET "https://api.booxi.com/booking/v1/groupEvent?
from=2022-01-25T09%3A00%3A00Z&to=2022-01-30T09%3A00%3A00Z&offset=0&limit=20"
-H "accept: application/json"
-H "Booxi-APIKey: YOUR_API_KEY_HERE"
You can test this API here (North America):
Retrieving events for several store locations can be done by using the same technique as described above. You must either repeat it for each merchant location, or send a single query with GET /merchantAvailability using your partner API Key. While using merchantAvailability, it is important to set the parameter serviceBookingMethod to “GroupReservation” to only receive group events. Make sure your partner API Key is only used in server code so as to preserve its secrecy.
Request URL
cURL
curl -X GET "https://api.booxi.com/booking/v1/merchantAvailability?
partnerId=YOUR_PARTNER_ID&
from=2022-01-29T09%3A00%3A00Z&to=2021-01-30T09%3A00%3A00Z&
serviceBookingMethod=GroupReservation"
-H "accept: application/json"
For more information on the /merchantAvailability API, refer to this link (North America):
If you created content in multiple languages, you should set the language parameter to match your website.
For all queries, date ranges must not exceed 180 days.
Group events matching your query will be returned in a JSON format, all events sorted by chronological order, with paging (if a cursor is returned, more results are available).
Here’s an example of a successful JSON response.
{
"offset": 0,
"limit": 10,
"total": 12,
"items": [
{
"id": 1,
"start": "2017-06-29T09:00:00Z",
"duration": 30,
"price": {...},
"location": "Business",
"locationText": "",
"staffId": 1,
"staffName": "string",
"staffFirstName": "Sample",
"staffLastName": "Employee",
"staff": {...},
"serviceId": 1,
"serviceName": "Sample Service",
"serviceCategoryId": 0,
"serviceCategoryName": "Main Services",
"service": {
"id": 1,
"merchantId": 1,
"name": "Self Printing",
"tags": "promotion,self-service",
"duration": 30,
"showDuration": true,
"hasDurationCustomization": false,
"bookingMethod": "Appointment",
"location": "Business",
"locationText": "",
"price": {...},
"categoryId": 0,
"categoryName": "Main Services",
"description": "...",
"profileImageUrl": "https://...",
"staffSelectionMode": "AssignedStaff",
"timeSelectionMode": "TimeSlot",
"maxReservationSize": 0,
"metadata": {
"referenceId": "102"
},
"surveyModel": {...}
},
"attendeeCount": 3,
"attendeeCapacity": 8,
"isCompleted": false,
"onlineBookingAllowedFrom": "2017-06-22T04:00:00Z",
"onlineBookingAllowedUntil": "2017-06-28T09:00:00Z",
"createdOn": "2017-06-20T15:42:13Z",
"metadata": {
"referenceId": "102"
}
}
]
"cursor": "string"
}Add Event to a Calendar
With data from the query, you can populate the calendar. In this example, the open source fullcalendar.io widget is used. For each event entry, make a call to fullCalendar’s addEventSource method using the name of the event, and store the event ID. The ID will be used to open the booking widget for that specific event.
Here are the properties of an event you can use:
Property | Description | Example |
id | ID associated with a group event, which you will need to open Book Now for that event. | "id": 1
|
start | The event’s starting date / time in RFC3339 format. You will need to adjust it to the browser local timezone. | "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 | The category ID and name associated with a service. These properties 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 a service. | "profileImageUrl": "https://..." |
description | A service’s description. | description": "..." |
attendeeCount attendeeCapacity | An event’s attendance and capacity. Can be used to display how many places are available. | "attendeeCount": 3, "attendeeCapacity": 8 |
createdBy | Who created the booking, “Client” for an online booking or “Staff” for an offline booking. | "createdBy": "Staff" |
In most cases, displaying the event’s name and duration in the calendar will suffice. The remaining data can be presented in an overlay or an event page where additional details and functionalities, such as selecting other dates and time for the same event, could be added.
Launch the Book Now Widget
Once an event is selected in the calendar, use any UI element of your choice to display the event’s details as well as a “Book Now” button. Simply map the button’s “onclick” event with a call to booxiController.open() to open the booking widget with the required parameters. The event ID assigned to a calendar entry should then be passed as a parameter to the booxiController.open() as shown below:
<div onclick="booxiController.open(null,{eventCalId:'YOUR_ID'});">Book</div>Once clicked, the booking widget will be opened with its associated event ID.
Additional Options
Filtering content by Store, Service or Service Category
Providing your clients the ability to filter your calendar’s content by selecting a store, a service or a category creates a better user experience. The API provides methods to retrieve such information that can be used to populate dropdown menus, lists or any other UI element. Using GET /service, you can obtain a list of services provided by a merchant. When a service is selected, the calendar’s content can be updated by matching the selected “serviceId”.
If your calendar displays events for multiple stores, note that service IDs are different per store. If you wish to filter content by service for multiple locations, consider using the service tag for this purpose. If all stores offer the same services, list the services of one store and use service tags with the API keyword parameter. Another option is to hardcode filter categories that you associate with service tags.