How to Build an Event Calendar Using the API

This article will help you understand 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 the Booking Widget 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 what needs to be done 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 time zone 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

https://api.booxi.com/booking/v1/groupEvent

 

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:

 

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” so 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

https://api.booxi.com/booking/v1/merchantAvailability

 

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):

https://api.booxi.com/doc/booking.html#/Availability/findAvailability

 

Take note that, 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, we use the open source fullcalendar.io widget. For each event entry, make a call to fullCalendar’s addEventSource method using the name of the event, and storing the event ID. The ID will later be used to open the Booking Widget for that specific event.

 

Here are the properties of an event you can use:

 

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 Booking 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 booking 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, please be reminded 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.

References

For more information about the API and its usage, refer to the following links:

• Europe: https://api.booxi.eu/doc/booking.html
• Americas: https://api.booxi.com/doc/booking.html

Where can API keys be found:

• Your Merchant API key can be found in the back office, section My Business / Business Details.
• Your Partner API key must be requested to your Booxi Account Manager. The Partner API key must only be used in server side (backend) code to keep it a secret.