The following article provides an overview of the Service API and explains how to use each of its endpoints.
Please take note that this API requires a Partner API Key. If you haven’t been provided with such a key, please contact your Booxi representative.
Be reminded that the URL at which you access the API depends on your hosting region. This article may present examples from a North American hosting only.
North America |
Europe |
api.booxi.com |
api.booxi.eu |
CRUD Endpoints
POST /service
Create a new Service.
Permissions & Security
- A Partner API key is required.
- The Partner API key provided must be valid.
- The merchantId provided must be associated with the Partner API key provided.
- The serviceId provided must be associated with a merchant that is associated with the Partner API key provided.
Requirements
- The merchantId provided must be valid and associated with an active merchant.
- The serviceId provided must be valid (and not deleted), and be associated with the merchantId, or with the HO merchantId in the same merchant group of the provided merchantId.
Parameters
There are no mandatory parameters for this endpoint. You only need to enter the desired service details in the request body. If you want to create a service from a pre-existing one, use either of the below parameters:
Parameter |
Format |
Description |
fromServiceId |
integer |
The id of the service to duplicate. The service must belong to the same merchant. Optional. |
fromServiceTemplateId |
integer |
The id of the Head Office service template to use to create the service in a store. Optional. |
- Creating a service with the fromServiceId parameter will duplicate the basic info of the service and its booking rules, assigned staff, associated resources, service translations and picture.
- All information present in the payload will override the existing service information.
- The queryParam fromServiceTemplateId can be used to create a service in a store, from a service template defined in a Head Office merchant.
- Creating a service with the "fromServiceTemplateId" parameter will duplicate the basic info of the service and its booking rules, service translations and picture.
- It is equivalent to assigning the service template to a store, so a service can be created from template only once in a given store.
- All information present in the payload will override the existing service information.
Request URL for North America
https://api.booxi.com/booking/v1/service
Request URL for Europe
https://api.booxi.eu/booking/v1/service
cURL
curl -X POST "https://api.booxi.com/booking/v1/service"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
-H "Content-Type: application/json"
-d "{\"merchantId\":YOUR_MERCHANT_ID,\"name\":\"Self Printing\",\"tags\":\"promotion,self-service\",\"duration\":60,\"showDuration\":true,\"bookingMethod\":\"Appointment\",\"location\":\"Business\",\"locationText\":\"\",\"price\":{\"visibility\":\"Show\",\"amount\":\"10.00\",\"amountPerPerson\":\"5.99\",\"amountPerHour\":\"0.00\",\"isStartingAt\":false,\"tax\":\"Excluded\"},\"categoryId\":0,\"description\":\"Enjoy using all of our equipment at your leisure.\",\"instructions\":\"Please arrive 10 minutes before the start of your appointment.\",\"metadata\":{\"classification\":\"supplemental\"},\"surveyText\":\"Is this your first time here? # Yes # No\",\"surveyType\":\"Multiple\",\"isSurveyRequired\":false,\"status\":\"Offline\"}"
Successful Response
Here’s an example of a successful response.
{
"id": 376299,
"merchantId": YOUR_MERCHANT_ID,
"name": "Self Printing",
"tags": "promotion,self-service",
"duration": 60,
"showDuration": true,
"hasDurationCustomization": false,
"bookingMethod": "Appointment",
"location": "Business",
"locationText": "",
"price": {
"visibility": "Show",
"amount": "10.00",
"amountPerPerson": "5.99",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "Excluded"
},
"hasPriceCustomization": false,
"categoryId": 0,
"categoryName": "Main Services",
"description": "Enjoy using all of our equipment at your leisure.",
"profileImageUrl": "",
"staffSelectionMode": "AssignedStaff",
"timeSelectionMode": "TimeSlot",
"instructions": "Please arrive 10 minutes before the start of your appointment.",
"metadata": {
"classification": "supplemental"
},
"surveyModel": {
"pages": [
{
"name": "default",
"elements": [
{
"name": "_question1",
"type": "text",
"title": "Is this your first time here? # Yes # No",
"isRequired": false
}
]
}
]
},
"isSurveyRequired": false,
"surveyText": "Is this your first time here? # Yes # No",
"surveyType": "Multiple",
"status": "Offline",
"isTemplate": false,
"createdOn": "2024-07-30T14:42:52Z",
"modifiedOn": "2024-07-30T14:42:52Z"
You can test this endpoint at the following links.
For North America |
For Europe |
GET /service/{serviceId}
Retrieves the details of a specific service.
Permissions & Security
- A Partner API key is required.
- The Partner API key provided must be valid.
- The serviceId provided must belong to an active merchant that is associated with the Partner API key provided.
Requirements & Specifications
- The serviceId provided must exist (i.e. not deleted).
Parameters
Parameter |
Format |
Description |
serviceId |
integer |
The id of the service. |
Request URL for the North America
https://api.booxi.com/booking/v1/service/YOUR_SERVICE_ID
Request URL for Europe
https://api.booxi.eu/booking/v1/service/YOUR_SERVICE_ID
cURL
curl -X GET "https://api.booxi.com/booking/v1/service/YOUR_SERVICE_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
Successful Response
Here’s an example of a successful response.
{
"id": 1111,
"merchantId": 2222,
"name": "Manicure",
"tags": "",
"duration": 60,
"showDuration": true,
"hasDurationCustomization": false,
"bookingMethod": "Appointment",
"location": "Business",
"locationText": "",
"price": {
"visibility": "Show",
"amount": "50.00",
"amountPerPerson": "0.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "Excluded"
},
"hasPriceCustomization": false,
"categoryId": 52860,
"categoryName": "Nail Treatments",
"description": "",
"profileImageUrl": "",
"staffSelectionMode": "AssignedStaff",
"timeSelectionMode": "TimeSlot",
"instructions": "",
"metadata": {},
"surveyText": "",
"status": "Online",
"serviceTemplateId": 365932,
"isTemplate": false,
"createdOn": "2024-05-02T16:55:45Z",
"modifiedOn": "2024-06-12T19:20:26Z"
}
You can test this endpoint at the following links.
For North America |
For Europe |
GET /service/list
Retrieve services matching a moduleLink external id. The service information can be accessed even if the service is not available online.
Permissions & Security
- A Partner API key is required.
- The provided Partner API key must be valid.
- The service found by externalId must be associated with a merchant that is accessible with the provided Partner API key or Merchant API key (existing).
- The Partner API key must be authorized to be used for the provided moduleId.
Requirements & Specifications
- The merchantId provided must be valid.
- The merchantId provided must be associated with an active merchant.
- The moduleId must be valid and the externalId parameter must be present.
- The moduleId provided must be associated with the Partner API key provided.
- The moduleId and externalId must not exceed 128 characters.
- Return a HTTP 200 with an empty list if parameters are valid but produce no results.
*Notes:
- The moduleId to use when searching the service via API is "cegid_y2".
- The externalId is the value set in the "Y2 Product Id" field (see service details).
- Results are sorted by service name, then service id.
- Pagination is done with a cursor and the page size can vary.
- If parameters are valid but produce no results, a 200 code will be returned with an empty list.
- Deleted services will not be included in the list of results.
Parameters
Parameter |
Format |
Description |
externalId |
string |
The external id of the service in the module defined by moduleId. Required to use moduleId, optional otherwise. |
moduleId |
string |
The id of the module to search in. Required to use externalId, optional otherwise. |
merchantId |
integer |
The merchant id to which the services belong. Required if not searching with externalId, optional otherwise. |
serviceCategoryId |
integer |
The id of the category the services are in. Optional, cannot be used when searching with externalId. For default category (“Main services”), enter 0. |
tags |
string |
A comma separated list of keywords to filter which services are searched in (see Booking Filter Tags). Optional. |
bookingMethod |
string |
The booking method of the service. Optional. Available values : Appointment, GroupReservation, Rental |
status |
string |
The status of the service. Optional. Available values : Online (1), Offline (0) |
cursor |
string |
A token to get the next set of results of a request. When the cursor is set, all other query parameters must NOT be set. |
Case 1 (using externalId and moduleId)
Request URL for the North America
https://api.booxi.com/booking/v1/service/list?externalId=YOUR_EXTERNAL_ID&moduleId=YOUR_MODULE_ID
Request URL for Europe
https://api.booxi.eu/booking/v1/service/list?externalId=YOUR_EXTERNAL_ID&moduleId=YOUR_MODULE_ID
cURL
curl -X GET "https://api.booxi.com/booking/v1/service/list?externalId=YOUR_EXTERNAL_ID&moduleId=YOUR_MODULE_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNEY_API_KEY"
Case 2 (using merchant Id)
Request URL for North America
https://api.booxi.com/booking/v1/service/list?merchantId=YOUR_MERCHANT_ID
Request URL for Europe
https://api.booxi.eu/booking/v1/service/list?merchantId=YOUR_MERCHANT_ID
cURL
curl -X GET "https://api.booxi.com/booking/v1/service/list?merchantId=YOUR_MERCHANT_ID"
-H "accept: application/json"
-H "Booxi-PartnerKey: YOUR_PARTNEY_API_KEY"
Successful Response
Here’s an example of a successful response.
{
"services": [
{
"id": 370522,
"merchantId": 11359,
"name": "service A",
"tags": "",
"duration": 60,
"showDuration": true,
"hasDurationCustomization": false,
"bookingMethod": "Appointment",
"location": "Business",
"locationText": "",
"price": {
"visibility": "Show",
"amount": "15.00",
"amountPerPerson": "0.00",
"amountPerHour": "0.00",
"currency": "CAD",
"isStartingAt": false,
"tax": "None"
},
"hasPriceCustomization": false,
"categoryId": 0,
"categoryName": "Main Services",
"description": "",
"profileImageUrl": "",
"staffSelectionMode": "Disabled",
"timeSelectionMode": "TimeSlot",
"instructions": "",
"metadata": {},
"surveyText": "",
"status": "Online",
"isTemplate": false,
"createdOn": "2024-06-12T19:21:35Z",
"modifiedOn": "2024-07-05T19:15:47Z"
}
]
}
You can test this endpoint at the following links.
For North America |
For Europe |
Limitations & Notes
- This API shall not be used to generate reports or export data.
- Modules must be configured and activated by Booxi before usage.
References
For more information about the Booxi APIs and their usage, please refer to the following links:
Americas: https://api.booxi.com/doc/booking.html
Europe: https://api.booxi.eu/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 is provided by your Booxi Account Manager. The Partner API key must only be used in server-side (backend) code to keep it a secret.