Use of the 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:
The Booxi API can easily be used to create a landing page to promote a single event and capture online booking through a custom experience. This article explains how to use the API to create a custom booking experience with the following simple steps:
Obtain a Partner API Key
Collect client and attendee information
Create a booking by calling POST /booking
Ask for an online payment (optional)
Update the booking with payment status by calling PUT /booking
This article doesn’t cover how to implement a payment solution to your website.
Booxi can be configured to automatically cancel an unpaid booking after a delay, which is why we do not cover cancel booking in this article.
Using a Partner API Key
In order to use the /booking API, you’ll need a Partner API Key which must be obtained from your Booxi representative. Unlike the Merchant API Key, the Partner API key must only be used in server side (backend) code to keep it a secret.
Collect Information
To create a booking, you will need to collect information to identify the client and attendees. There are 3 common practices to do so:
Use the Book Now widget to avoid having to develop a custom booking experience. Simply assign the eventID as a parameter to “Book Now”.
Use a web session to retrieve the required client information such as name, email and mobile number to prefill the “Book Now” client’s form, or use the POST /booking API.
Create a client form to capture the minimal required information to use the POST /booking API.
If you prefer not to capture attendee identification, you can use placeholders such as Attendee 1, Attendee 2 and so on. However, the client information is mandatory.
Create a Booking
To book an appointment or a reservation in a group event, call the POST /booking API. Make sure the data is properly formatted as shown in the example below. Pay special attention to “bookingMethod” and “groupEventId” as they are specific to group reservations. Note that the “Group Event ID” must be created in your Booxi calendar beforehand.
If your service is configured to immediately send the booking confirmation (not after payment is completed), this API call will also trigger the release of the confirmation message to the client. If you use the Booxi webhook, you can also listen to the reservation.created event which will be triggered when calling this API.
Request Body
{
"merchantId": YOUR_MERCHANT_ID,
"bookingMethod": "GroupReservation",
"groupEventId": YOUR_GROUP_EVENT_ID,
"client": {
"firstName": "Mike",
"lastName": "Abbott",
"email": "mike.abbott@domain.com",
"homePhoneNumber": "111-222-3333",
"mobilePhoneNumber": "444-555-6666",
"remindByEmail": true,
"remindBySMS": false,
"isAttending": true
},
"attendees": [
{
"firstName": "Mike",
"lastName": "Abbott",
"email": "mike.abbott@domain.com",
"homePhoneNumber": "111-222-3333",
"mobilePhoneNumber": "444-555-6666",
"remindByEmail": true,
"remindBySMS": false,
"isRequester": true
}
],
"clientCommunication": "ClientAndAttendees",
"createdBy": "Client"
}
Request URL
cURL
curl -X POST
"https://api.booxi.com/booking/v1/booking?rules=&language=eng"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{\"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\"}"
Pay attention to the following properties:
Property | Description | Example |
client.isAttending | Set to true if the client who makes the reservation is also attending. | "isAttending": true
|
attendee.isRequester | Identifies (true) which attendee is the client who made the reservation. | "isRequester": true |
clientCommunication | Identifies who will receive notification messages for this reservation. Possible values are: “DoNotSend”, “ClientOnly” and “ClientAndAttendees” | "clientCommunication":"DoNotSend" |
Once the booking is successful, Booxi will send a response as a JSON object. The JSON object will include important information such as the bookingId and onlinePaymentId. Both will be required to collect payment and keep the records up-to-date.
Here is an example of a successful response:
{
"bookingId": "A00001234",
"merchantId": 1002,
"bookingMethod": "Appointment",
"status": "Approved",
"isCompleted": false,
"startsOn": "2022-02-20T16:00:00Z",
"totalClientTimespan": {
"start": "2022-02-20T16:00:00Z",
"end": "2022-02-20T16:30:00Z",
"duration": 30
},
"staffId": 582,
"items": [
{
"serviceId": 1000,
"serviceName": "...",
"price": {
"visibility": "Show",
"amount": "5.00",
"amountPerPerson": "0.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "None"
},
"reservedClientTimespan": {
"start": "2022-02-20T16:00:00Z",
"end": "2022-02-20T16:30:00Z",
"duration": 23
},
"duration": 23,
"spacingAfter": 0,
"isBusySpacingAfter": true
}
],
"location": "Business",
"locationText": "",
"client": {
"firstName": "Emilie",
"lastName": "Authier",
"email": "emilie.authier@booxi.com",
"homePhoneNumber": "",
"mobilePhoneNumber": "",
"presence": "Expecting",
"remindByEmail": false,
"remindBySMS": false,
"additionalRequest": ""
},
"payment": {
"total": "5.00",
"paid": "0.00",
"onlinePaymentId": "P00001234",
"onlinePaymentAmount": "2.00",
"onlinePaymentStatus": "Requested"
},
"createdOn": "2022-01-17T20:10:38Z",
"createdBy": "Staff",
"modifiedOn": "2022-01-17T20:10:38Z",
"modifiedBy": "Staff",
"isScheduled": true,
"clientCount": 1
}
If your event requires payment, now would be the time to redirect your client to a payment solution such as a shopping cart or a payment/checkout page.
Collect Payment (optional)
Using the information found in the JSON object sent by Booxi, you can collect the payment associated with your event. To do so, consider one of the following options:
Use the Shopping Cart Redirection
If you are using the Book Now widget, consult this article to learn how to redirect your clients to your shopping cart.
Use a Payment or Checkout Page
If you are using a payment or checkout page, see below to learn how to update the payment status.
Update Booking with Payment Status
Update the booking payment status by calling PUT /booking/{bookingId}/payment/{paymentId} using your booking and online payment id. If your service is configured to send the booking confirmation once the full payment is completed, this API call will also trigger the release of the confirmation message to the client. If you use the Booxi webhook, you can also listen to the appointment.online_payment event which will be triggered when calling this API. The updated booking data should be formatted as per the example shown below:
Request Body
{
"status": "Collected",
"amount": "10.00",
"referenceNumber": "YOUR_REFERENCE_NUMBER"
}Request URL
cURL
curl -X PUT
"https://api.booxi.com/booking/v1/booking/A00001234/payment/P00001234"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{\"status\":\"Collected\",\"amount\":\"10.00\",\"referenceNumber\":\"\"}"
Once the payment has been recorded successfully, Booxi will, once again, send a response.
{
"payment": {
"id": "P00001234",
"bookingId": "A00001234",
"merchantId": 1,
"paymentMethod": "ShoppingCart",
"status": "Requested",
"amount": "10.99",
"referenceNumber": "cart_1G4DO62eZvKYlo2Cig7bioUp",
"createdOn": "2021-01-17T07:15:00Z",
"collectedOn": "2021-01-17T07:15:01Z"
}
}
With this information, you can now update your own records and complete the process.