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:
What are store schedules?
Store schedules are by definition the hours during which a store is doing business and accepting bookings. While only one schedule can be active at a time, Booxi allows creating several schedules to meet specific needs or changing business hours throughout the year (i.e. end-of-year holidays, summer time, etc.).
What are staff schedules?
Staff schedules describe the period of time a member of staff is working or available for booking. A staff work schedule can be set by using one of the following options:
Open Hours
Used for staff that work during business hours.
Weekly Work Schedule
Used for staff requiring more flexible work hours (schedule defined on a weekly basis).
Calendar
Used for staff with no fixed schedule (by default unavailable, staff must create available time slots to make them available).
For more info about these options, see here.
Availability
Store availability is determined by the open hour schedule currently active (marked with a green dot in the Back Office). Availability can be changed by assigning a different schedule or by creating a new one.
Staff availability is determined by a staff member's work hour schedule (open hours, weekly work schedule or calendar) minus any busy time slots added to their calendar.
Schedules API
The Schedules API provides endpoints to retrieve, create, update and delete both store and staff schedules. Note that any operation performed on schedules will have an impact on availability and may result in limited booking opportunities. Make sure the operation to be performed will generate the expected result.
Store Schedule
Retrieving a store’s schedules
To retrieve schedules assigned to a store, use the GET/merchant/{merchantId}/schedule endpoint. Your request must minimally include a merchant Id. Additional parameters are available to limit the request’s range.
Mandatory Parameters
Parameter | Format | Description |
merchantId | merchantId={merchantId} merchantId=8099 | The id of the target store. |
Optional Parameters
Parameter | Format | Description |
rangeStart | rangeStart={date} rangeStart=2022-01-01 | Beginning of the date range to retrieve schedules from. |
rangeEnd | rageEnd={date} rangeStart=2024-01-01 | End of the date range to retrieve schedules from. |
cursor | cursor={cursor} "cursor": "sl_eJxjZGALcmVgYGdQTtjGAK" | A token to get the next set of results associated with a request. When the cursor is set, all other query parameters should NOT be set. |
Limitations
Retrieving schedules by date range is limited to 1 year in the past and 10 years in the future.
Request URL for North America
https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule
cURL
curl -X GET
"https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include schedules associated with the specified store for the range of time provided (if any).
Here’s an example of a successful response:
{
"schedules": [
{
"id": 1,
"name": "Holiday Season 2023",
"description": "Holidays 2023",
"start": "2023-12-21",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
}
]
}
],
"cursor": "sl_eJxjZGALcmVgYGdQTtjGAKJ9cvSBDNgBBjAAAFWgBPU"
}Retrieving a specific store schedule
To retrieve a specific store schedule, use the GET/merchant/{merchantId}/schedule/{scheduleId} endpoint. Your request must minimally include a merchant Id and a schedule Id.
Mandatory Parameters
Parameter | Format | Description |
merchantId | merchantId={merchantId} merchantId=8099 | The id of the target store. |
scheduleId | scheduleId={scheduleId} scheduleId=13865 | The id associated with the schedule to retrieve. |
Request URL for North America
https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID
cURL
curl -X GET
"https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include the requested schedule and its details.
Here’s an example of a successful response:
{
"id": 1,
"name": "Holiday Season 2023",
"description": "Holidays 2023",
"start": "2023-12-21",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
}
]
}Creating a new store schedule
To create a new store schedule, use the POST/merchant/{merchantId}/schedule endpoint. Your request must minimally include a merchant Id and a request body.
Mandatory Parameters
Parameter | Format | Description |
merchantId | merchantId={merchantId} merchantId=8099 | The id of the target store. |
requestBody | see below for details on its content. | All details related to the new schedule to create. |
Limitations
Creating overlapping schedules is not permitted nor supported.
Request URL for North America
https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule
cURL
curl -X POST
"https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
-d "{\"id\":1,\"name\":\"Holiday Season 2023\",\"description\":\"Holidays 2023\",
\"start\":\"2023-12-21\",\"end\":\"2023-12-31\",\"weeklyHours\":[{\"dow\":1,\"start\":\"10:00:00\",\"end\":\"18:00:00\"}]}"
Request Body
{
"name": "Holiday Season 2023",
"description": "Holidays 2023",
"start": "2023-12-21",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
}
]
}You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include the new schedule and its details.
Here’s an example of a successful response:
{
"id": 1,
"name": "Holiday Season 2023",
"description": "Holidays 2023",
"start": "2023-12-24",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
}
]
}Updating a store schedule
To update a store schedule, use the PUT/merchant/{merchantId}/schedule/{scheduleId} endpoint. Your request must minimally include a merchant Id, a schedule Id and a request body.
Mandatory Parameters
Parameter | Format | Description |
merchantId | merchantId={merchantId} merchantId=8099 | The id of the target store. |
scheduleId | scheduleId={scheduleId} scheduleId=13865 | The id associated with the schedule to retrieve. |
requestBody | see below for details on its content. | All details related to the schedule to update. |
Request URL for North America
https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID
cURL
curl -X GET
"https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
-d "{\"id\":1,\"name\":\"Holiday Season 2023\",\"description\":\"Holidays 2023\",
\"start\":\"2023-12-24\",\"end\":\"2023-12-31\",\"weeklyHours\":[{\"dow\":1,\"start\":\"10:00:00\",\"end\":\"18:00:00\"}]}"
Request Body
{
"id": 1,
"name": "Holiday Season 2023",
"description": "Holidays 2023",
"start": "2023-12-24",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
}
]
}You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include the updated schedule and its details.
Here’s an example of a successful response:
{
"id": 1,
"name": "Holiday Season 2023",
"description": "Holidays 2023",
"start": "2023-12-24",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
}
]
}Deleting a store schedule
To delete an existing store schedule, use the DELETE/merchant/{merchantId}/schedule/{scheduleId} endpoint. Your request must minimally include a merchant Id and a schedule Id. Note that this operation cannot be undone and may impact a store’s availability.
Mandatory Parameters
Parameter | Format | Description |
merchantId | merchantId={merchantId} merchantId=8099 | The id of the target store. |
scheduleId | scheduleId={scheduleId} scheduleId=13865 | The id associated with the schedule to retrieve. |
Request URL for North America
https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID
cURL
curl -X GET
"https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include the deleted schedule and its details.
Here’s an example of a successful response:
{
"id": 1,
"name": "Holiday Season 2023",
"description": "Holidays 2023",
"start": "2023-12-24",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
}
]
}Staff Schedule
Retrieving a staff member’s schedules
To retrieve schedules assigned to a staff member, use the GET/staff/{staffId}/schedule endpoint. Your request must minimally include a staff Id. Additional parameters are available to limit the request’s range.
Mandatory Parameters
Parameter | Format | Description |
staffId | staffId={staffId} staffId=21750 | The id of the target staff member. |
Optional Parameters
Parameter | Format | Description |
rangeStart | rangeStart={date} rangeStart=2022-01-01 | Beginning of the date range to retrieve schedules from. |
rangeEnd | rageEnd={date} rangeStart=2024-01-01 | End of the date range to retrieve schedules from. |
cursor | cursor={cursor} "cursor": "sl_eJxjZGALcmVgYGdQTtjGAK" | A token to get the next set of results associated with a request. When the cursor is set, all other query parameters should NOT be set. |
Request URL for North America
https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule
cURL
curl -X GET
"https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include schedules associated with the member of staff for the range of time provided (if any).
Here’s an example of a successful response:
{
"schedules": [
{
"id": 2,
"name": "Fourth Quarter 2023",
"description": "4TH-2023",
"start": "2023-10-01",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
},
{
"dow": 2,
"start": "10:00:00",
"end": "18:00:00"
}
]
}
]
"cursor": "sl_eJxjZGALcmVgYGdQTtjGAK"
}Retrieving a specific staff schedule
To retrieve a specific staff schedule, use the GET/staff/{staffId}/schedule/{scheduleId} endpoint. Your request must minimally include a staff Id and a schedule Id.
Mandatory Parameters
Parameter | Format | Description |
staffId | staffId={staffId} stafId=21750 | The id of the target staff member. |
scheduleId | scheduleId={scheduleId} scheduleId=13865 | The id associated with the schedule to retrieve. |
Request URL for North America
https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID
cURL
curl -X GET
"https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include the requested schedule and its details.
Here’s an example of a successful response:
{
"id": 2,
"name": "Fourth Quarter 2023",
"description": "4TH-2023",
"start": "2023-10-01",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
},
{
"dow": 2,
"start": "10:00:00",
"end": "18:00:00"
}
]
}Creating a new staff schedule
To create a new staff schedule, use the POST/staff/{staffId}/schedule endpoint. Your request must minimally include a staff Id and a request body.
Mandatory Parameters
Parameter | Format | Description |
staffId | staffId={staffId} stafId=21750 | The id of the target staff member. |
requestBody | see below for details on its content. | All details related to the new schedule to create. |
Request URL for North America
https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule
cURL
curl -X POST
"https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
-d "{\"id\":1,\"name\":\"Holiday Season 2023\",\"description\":\"Holidays 2023\",
\"start\":\"2023-12-21\",\"end\":\"2023-12-31\",\"weeklyHours\":[{\"dow\":1,\"start\":\"10:00:00\",\"end\":\"18:00:00\"}]}"
Request Body
{
"name": "Fourth Quarter 2023",
"description": "4TH-2023",
"start": "2023-10-01",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
},
{
"dow": 2,
"start": "10:00:00",
"end": "18:00:00"
}
]
}You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include the new schedule and its details.
Here’s an example of a successful response:
{
"id": 2,
"name": "Fourth Quarter 2023",
"description": "4TH-2023",
"start": "2023-10-01",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "10:00:00",
"end": "18:00:00"
},
{
"dow": 2,
"start": "10:00:00",
"end": "18:00:00"
}
]
}Updating a staff schedule
To update/modify a staff schedule, use the PUT/staff/{staffId}/schedule/{scheduleId} endpoint. Your request must minimally include a staff Id, a schedule Id and a request body.
Mandatory Parameters
Parameter | Format | Description |
staffId | staffId={staffId} stafId=21750 | The id of the target staff member. |
scheduleId | scheduleId={scheduleId} scheduleId=13865 | The id associated with the schedule to retrieve. |
requestBody | see below for details on its content. | All details related to the schedule to update. |
Request URL for North America
https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID
cURL
curl -X GET
"https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
-d "{\"id\":2,\"name\":\"Fourth Quarter 2023\",\"description\":\"4TH-2023\",
\"start\":\"2023-10-01\",\"end\":\"2023-12-31\",\"weeklyHours\":[{\"dow\":1,\"start\":\"12:00:00\",\"end\":\"18:00:00\"},{\"dow\":2,\"start\":\"12:00:00\",\"end\":\"18:00:00\"}]}"
Request Body
{
"id": 2,
"name": "Fourth Quarter 2023",
"description": "4TH-2023",
"start": "2023-10-01",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "12:00:00",
"end": "18:00:00"
},
{
"dow": 2,
"start": "12:00:00",
"end": "18:00:00"
}
]
}You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include the updated schedule and its details.
Here’s an example of a successful response:
{
"id": 2,
"name": "Fourth Quarter 2023",
"description": "4TH-2023",
"start": "2023-10-01",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "12:00:00",
"end": "18:00:00"
},
{
"dow": 2,
"start": "12:00:00",
"end": "18:00:00"
}
]
}Deleting a staff schedule
To delete an existing staff schedule, use the DELETE/staff/{staffId}/schedule/{scheduleId} endpoint. Your request must minimally include a staffId and a schedule Id. Note that this operation cannot be undone and may impact staff availability.
Mandatory Parameters
Parameter | Format | Description |
staffId | staffId={staffId} stafId=21750 | The id of the target staff member. |
scheduleId | scheduleId={scheduleId} scheduleId=13865 | The id associated with the schedule to retrieve. |
Request URL for North America
https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID
cURL
curl -X GET
"https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
You can test this API at the following links.
For North America | For Europe |
Successful JSON Response
When the query is successful, the response will include the deleted schedule and its details.
Here’s an example of a successful response:
{
"id": 2,
"name": "Fourth Quarter 2023",
"description": "4TH-2023",
"start": "2023-10-01",
"end": "2023-12-31",
"weeklyHours": [
{
"dow": 1,
"start": "12:00:00",
"end": "18:00:00"
},
{
"dow": 2,
"start": "12:00:00",
"end": "18:00:00"
}
]
}Status Codes & Error Messages
The API returns data in a JSON format as well as standard HTTP status codes.
Code | Status | Description |
200 | OK | The request was completed successfully. |
400 | Bad Request | Error caused by an invalid request. Example: requesting a resource using an incorrect ID. |
401 | Unauthorized | The request hasn’t been completed because it lacks valid authentication credentials. Example: Using an incorrect API Key. |
403 | Forbidden | The request hasn’t been completed because it lacks appropriate permissions. Example:. Your API key doesn’t grant access to the requested resource (using a merchant API key where a partner API key is expected). |
404 | Not Found | The requested resource cannot be found on the server. Example: requesting a resource that has been deleted. |
409 | Conflict | The request conflicts with the current state of the targeted resource. Example: creating a new time slot that overlaps with an existing one. |
500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request. Example: a connection to the server cannot be established. |
Limitations
Schedules shown in the Back Office (“My Business” > “Open hours” and “Personnel” > “Work schedule” > “Weekly work schedule”) are limited to 100 entries. If you create schedules for individual days (e.g.: from Jan 1-Jan 1, Jan 2-Jan 2), your schedule count may be higher than 100 and therefore some of your data will not be shown. For this reason, we strongly recommend creating schedules for a longer period of time, such as weekly, bi-weekly, monthly, yearly or seasonal (see here for more info); this is in fact how the schedule functionality is intended to be used.
Creating overlapping schedules is neither permitted nor supported.
Retrieving schedules by date range is limited to one year in the past and 10 years in the future.
The authentication method requires a secure environment.
The endpoint must not be exposed on a webpage but rather server side.
Endpoints may have their own limitations, please consult our online swagger for more information.
Calls per API key shall not exceed 5 requests per second with a maximum of 300 requests per minute. Exceeding this quota will return a 429 error. Respecting this quota and handling any 429 errors are the responsibility of the client. It is recommended to make API calls with an interval of at least 10 milliseconds between each request. Any API calls generating 400 errors will count as double requests for the quota.
The use of Booxi API is solely authorized to conduct legal business by the client or a consultant under contractual agreement. Any usage for spam or reported as abusive is strictly prohibited and will result in the revocation of the API access. It is also prohibited to resell the use of the API. For further details, please consult our terms of service.