The Booxi API now provides a way to retrieve a client’s booking history with a simple API call. It could be employed to provide clients access to their booking history or, in a clienteling application, a way for your staff to review past and upcoming bookings of a client.
| ⚠️ | This API is not made to perform data replication by calling it on a frequent basis to update an external database. For such a purpose, the webhook should be employed. |
Please take note that this implementation requires a partner API Key. If you haven’t been provided with such a key, please contact your Booxi representative.
When querying a client’s booking history, the client id must belong to a clientele that is associated with a merchant that is accessible with your partner API key.
Be reminded that the URL you should use depends on your hosting region. This article presents examples from a North American hosting.
| North America | Europe |
| api.booxi.com | api.booxi.eu |
Retrieving a Client’s Booking History
To retrieve a client’s booking history, use the GET /booking?clientId={clientId}/ API. Your request must minimally include a starting and ending date and a valid clientId. Optional parameters are available to further filter out the results.
Mandatory Parameters
| Parameter | Format | Description |
|
from |
from={from} from=2022-01-01T00%3A00%3A00Z |
Starting date in RFC3339 format. |
|
to |
to={to} to=2022-12-31T00%3A00%3A00Z |
Ending date in RFC3339 format. |
|
clientId |
clientId={clientId} clientId=1111 |
Client Id the query should be performed for. |
Request URL for North America
https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}
cURL
curl -X GET
"https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_KEY"
Request URL for Europe
https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}
cURL
curl -X GET
"https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_KEY"
Optional Parameters
| Parameter | Format | Description |
|
merchantId |
merchantId={merchantId} merchantId=31386 |
Limit bookings assigned to a given merchant. |
|
bookingMethod |
bookingMethod={type} bookingMethod=Appointment |
Limit bookings to a specific type. Supported values are:
Default to all types. |
|
order |
order={order} order=ascending |
List results in ascending or descending order. Supported values are:
|
|
language |
language={language} language=eng |
Choose what language the results will be provided in. The code must be in ISO 639-3 format except for French which uses “fre”. The language is used for ready-only properties of an object that are generated by Booxi, localizable properties (ex: service name) and certain errors. Defaults to the authenticated merchant's preferred language. The API also accepts ISO 639-1 and ISO 639-2 codes. The following languages are supported: eng, fre, spa, por, nld, deu, ita, ron, pol, yue, jpn, ell, dan, swe, bul, rus, kor, ces. |
Example with all parameters:
Request URL for North America
https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}&merchantId={merchantId}&bookingMethod={type}&order={order}&language={language}
cURL
curl -X GET
"https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}&merchantId={merchantId}&bookingMethod={type}&order={order}&language={language}"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_KEY"
Request URL for Europe
https://api.booxi.eu/booking/v1/booking?from={from}&to={to}&clientId={clientId}&merchantId={merchantId}&bookingMethod={type}&order={order}&language={language}
cURL
curl -X GET
"https://api.booxi.eu/booking/v1/booking?from={from}&to={to}&clientId={clientId}&merchantId={merchantId}&bookingMethod={type}&order={order}&language={language}"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_KEY"
You can test this API at the following links.
| North America | Europe |
| findBooking | findBooking |
Successful JSON Response
When the query is successful, the response will include a list of all bookings that meet the query’s criteria. Take note that the response also contains a list of group events, services, staff and merchant objects that are referred by ID in the booking object. That extra data isn’t unique to the booking object.
| Response Fields | Description |
|
bookings |
Array of bookings that meet the query’s criteria. The booking object contains the same information as used in bookings created via the API. |
|
groupEvents |
Array of group events referenced in the bookings. |
|
services |
Array of all services provided in the bookings. |
|
staff |
Array of all staff referenced in the bookings. |
|
merchants |
Array of all merchants referenced in the bookings. |
Here’s an example of a successful response:
{
"bookings": [
{
"bookingId": "A00001234",
"merchantId": 100,
"bookingMethod": "Appointment",
"status": "Approved",
"isCompleted": false,
"startsOn": "2020-10-01T14:00:00Z",
"totalClientTimespan": {
"start": "2020-01-04T12:00:00Z",
"end": "2020-01-04T12:45:00Z",
"duration": 45
},
"staffId": 582,
"staffFirstName": "Jane",
"staffLastName": "Poe",
"items": [
{
"serviceId": 1001,
"serviceName": "French Cooking Tutorial",
"price": {
"visibility": "Show",
"amount": "10.00",
"amountPerPerson": "5.99",
"amountPerHour": "0.00",
"currency": "USD",
"isStartingAt": false,
"tax": "Excluded"
},
"reservedClientTimespan": {
"start": "2020-01-04T12:00:00Z",
"end": "2020-01-04T12:45:00Z",
"duration": 45
},
"shoppingCartProductId": "ID-199"
}
],
"location": "Business",
"locationText": "",
"client": {
"id": 1901,
"firstName": "Emilie",
"lastName": "Authier",
"email": "emilie.authier@booxi.com",
"homePhoneNumber": "+15552346789",
"mobilePhoneNumber": "+15552346789",
"presence": "Expecting",
"remindByEmail": true,
"remindBySMS": true,
"additionalRequest": "Can we bring our own ingredients?"
},
"payment": {
"total": "10.99",
"paid": "0.00",
"onlinePaymentId": "P000123",
"onlinePaymentAmount": "2.00",
"onlinePaymentStatus": "Requested"
},
"createdOn": "2020-01-01T07:15:00Z",
"createdBy": "Staff",
"modifiedOn": "2020-01-01T07:30:00Z",
"modifiedBy": "Staff"
}
],
"groupEvents": [
{
"id": 1,
"start": "2017-06-29T09:00:00Z",
"duration": 30,
"price": {
"visibility": "Show",
"amount": "10.00",
"amountPerPerson": "5.99",
"amountPerHour": "0.00",
"currency": "USD",
"isStartingAt": false,
"tax": "Excluded"
},
"location": "Business",
"locationText": "",
"staffId": 1,
"staffName": "string",
"staffFirstName": "Sample",
"staffLastName": "Employee",
"staff": {
"id": 1,
"name": "Jane Poe",
"firstName": "Jane",
"lastName": "Poe",
"position": "Manager",
"biography": "The friendly manager.",
"profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQX.png",
"timeSelectionMode": "ServiceTimeSelection"
},
"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": {
"visibility": "Show",
"amount": "10.00",
"amountPerPerson": "5.99",
"amountPerHour": "0.00",
"currency": "USD",
"isStartingAt": false,
"tax": "Excluded"
},
"hasPriceCustomization": false,
"categoryId": 0,
"categoryName": "Main Services",
"description": "Enjoy using all of our equipment at your leisure.",
"profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQB.png",
"staffSelectionMode": "AssignedStaff",
"timeSelectionMode": "TimeSlot",
"maxReservationSize": 0,
"bookingPolicy": "Any modification or cancellation must be done at least 24 h before the appointment time.",
"instructions": "Please arrive 10 minutes before the start of your appointment.",
"metadata": {
"classification": "supplemental"
},
"surveyModel": {
"pages": {
"name": "default",
"elements": [
{
"type": "text",
"name": "Q1",
"title": "Is this your first time here?"
}
]
}
}
},
"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": {
"classification": "supplemental"
}
}
],
"services": [
{
"id": 1,
"merchantId": 1,
"name": "Self Printing",
"tags": "promotion,self-service",
"duration": 30,
"showDuration": true,
"hasDurationCustomization": false,
"bookingMethod": "Appointment",
"location": "Business",
"locationText": "",
"price": {
"visibility": "Show",
"amount": "10.00",
"amountPerPerson": "5.99",
"amountPerHour": "0.00",
"currency": "USD",
"isStartingAt": false,
"tax": "Excluded"
},
"hasPriceCustomization": false,
"categoryId": 0,
"categoryName": "Main Services",
"description": "Enjoy using all of our equipment at your leisure.",
"profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQB.png",
"staffSelectionMode": "AssignedStaff",
"timeSelectionMode": "TimeSlot",
"maxReservationSize": 0,
"bookingPolicy": "Any modification or cancellation must be done at least 24 h before the appointment time.",
"instructions": "Please arrive 10 minutes before the start of your appointment.",
"metadata": {
"classification": "supplemental"
},
"surveyModel": {
"pages": {
"name": "default",
"elements": [
{
"type": "text",
"name": "Q1",
"title": "Is this your first time here?"
}
]
}
}
}
],
"staff": [
{
"id": 1,
"merchantId": 1,
"name": "Self Printing",
"tags": "promotion,self-service",
"duration": 30,
"showDuration": true,
"hasDurationCustomization": false,
"bookingMethod": "Appointment",
"location": "Business",
"locationText": "",
"price": {
"visibility": "Show",
"amount": "10.00",
"amountPerPerson": "5.99",
"amountPerHour": "0.00",
"currency": "USD",
"isStartingAt": false,
"tax": "Excluded"
},
"hasPriceCustomization": false,
"categoryId": 0,
"categoryName": "Main Services",
"description": "Enjoy using all of our equipment at your leisure.",
"profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQB.png",
"staffSelectionMode": "AssignedStaff",
"timeSelectionMode": "TimeSlot",
"maxReservationSize": 0,
"bookingPolicy": "Any modification or cancellation must be done at least 24 h before the appointment time.",
"instructions": "Please arrive 10 minutes before the start of your appointment.",
"metadata": {
"classification": "supplemental"
},
"surveyModel": {
"pages": {
"name": "default",
"elements": [
{
"type": "text",
"name": "Q1",
"title": "Is this your first time here?"
}
]
}
}
}
],
"merchants": [
{
"id": 1,
"name": "The Work Shop",
"isAvailableOnline": true,
"storeNumber": "US1210",
"groupId": 201,
"groupName": "Printing Co",
"groupCategoryId": 30,
"groupCategoryName": "Manhattan",
"address": {
"street": "123 Fake St",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "US"
},
"contactFirstName": "Jane",
"contactLastName": "Poe",
"phoneNumber": "+15553334444",
"email": "jane@example.com",
"tags": "self-service,open-late",
"websiteUrl": "",
"bookingUrl": "https://site.booxi.com/theworkshop?lang=eng",
"apiKey": "7L9K7N2QrELXYJ8PJBsAtSA7HuL3BgRs",
"description": "The Work Shop is a great place to find and buy work supplies.",
"coverImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQY.png",
"profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQZ.png",
"currency": "USD",
"tax1Name": "CST",
"tax1Rate": "0.0450",
"tax2Name": "",
"tax2Rate": "0",
"timeZone": "America/New_York",
"latitude": "40.6892361",
"longitude": "-74.0445726",
"defaultLanguage": "eng",
"openHours": [
{
"dow": 1,
"start": "09:00:00",
"end": "13:45:00"
}
]
}
],
"cursor": "string"
}
Limitations
- The authentication method requires a secure environment.
- The endpoint must not be exposed on a webpage but rather server side.
- The client booking history will not include rental bookings.
- The client booking history will not include unscheduled appointments.
References
For more information about Booxi APIs and their usage, please refer to the following links:
Europe: https://api.booxi.eu/doc/booking.html
Americas: https://api.booxi.com/doc/booking.html
Where to find API keys:
- 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.