How to use the Service Category API

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:
- North America
- Europe

GET /serviceCategory/list

Find service categories of a given store, or from an external id.

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The merchantId provided must be valid.
The merchantId provided must be associated with an active store.
The service categories found by externalId must be associated with a store that is accessible with the provided Partner API key.
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 Partner API key must be authorized to be used for the provided moduleId.

Parameters

Parameter	Format	Description
externalId	string	The external id of the service category 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 service categories belong. Required if not searching with externalId, optional otherwise.
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.

Request URL for North America

https://api.booxi.com/booking/v1/serviceCategory/list?merchantId=YOUR_MERCHANT_ID

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory/list?merchantId=YOUR_MERCHANT_ID

cURL

curl -X 'GET' \
'https://api.booxi.com/booking/v1/serviceCategory/list?merchantId=YOUR_MERCHANT_ID' \
-H 'accept: application/json' \
  -H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY'

Successful Response

Here’s an example of a successful response.

{
"serviceCategories": [
  {
    "id": 12345,
    "name": "Body Treatments",
    "description": "",
    "profileImageUrl": "",
    "merchantId": YOUR_MERCHANT_ID,
    "isTemplate": false,
    "serviceCategoryTemplateId": 56781
  },
  {
    "id": 12346,
    "name": "Hair Care treatments",
    "description": "",
    "profileImageUrl": "",
    "merchantId": YOUR_MERCHANT_ID,
    "isTemplate": false,
    "serviceCategoryTemplateId": 56782
  },
  {
    "id": 12347,
    "name": "Nail Treatments",
    "description": "",
    "profileImageUrl": "",
    "merchantId": YOUR_MERCHANT_ID,
    "isTemplate": false,
    "serviceCategoryTemplateId": 56783
  }
]
}

You can test this endpoint at the following links.

For North America	For Europe
getServiceCategoryList	getServiceCategoryList

POST /serviceCategory

Create a new Service Category.

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The merchantId provided must be associated with the Partner API key provided.
The merchantId provided must be valid and associated with an active store.

Request URL for North America

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

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory

cURL

curl -X 'POST' \
'https://api.booxi.com/booking/v1/serviceCategory' \
-H 'accept: application/json' \
-H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"merchantId": YOUR_MERCHANT_ID,
"name": "Manicure",
"description": "All-in-one nail service."
}'

Successful Response

Here’s an example of a successful response.

{
"id": 12345,
"name": "Manicure",
"description": "All-in-one nail service.",
"profileImageUrl": "",
"merchantId": YOUR_MERCHANT_ID,
"isTemplate": false
}

You can test this endpoint at the following links.

For North America	For Europe
createServiceCategory	createServiceCategory

GET serviceCategory/{serviceCategoryId}

Retrieves the details of a specific service category.

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The serviceCategoryId provided must belong to an active store that is associated with the Partner API key provided.

Parameters

Parameter	Format	Description
serviceCategoryId	integer	The id of the service category

Request URL for North America

https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID

cURL

curl -X 'GET' \
'https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID' \
-H 'accept: application/json' \
  -H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY'

Successful Response

Here’s an example of a successful response.

{
"id": 12345,
"name": "Nail Treatments",
"description": "",
"profileImageUrl": "",
"merchantId": 11359,
"isTemplate": false,
"serviceCategoryTemplateId": 56789
}

You can test this endpoint at the following links.

For North America	For Europe
getServiceCategory	getServiceCategory

PUT /serviceCategory/{serviceCategoryId}

Update a service category.

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The serviceCategoryId provided must be valid.
The serviceCategoryId provided must belong to an active store that is associated with the Partner API key provided.

Parameters

Parameter	Format	Description
serviceCategoryId	integer	The id of the service category

Request URL for North America

https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE _CATEGORY_ID

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory/YOUR_SERVICE _CATEGORY_ID

cURL

curl -X 'PUT' \
'https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID' \
-H 'accept: application/json' \
-H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Nail Treatments",
"description": "Comprehensive nail services for all ages."
}'

Successful Response

Here’s an example of a successful response.

{
"id": 52860,
"name": "Nail Treatments",
"description": "Comprehensive nail services for all ages.",
"profileImageUrl": "",
"merchantId": YOUR_MERCHANT_ID,
"isTemplate": false,
"serviceCategoryTemplateId": YOUR_SERVICE_TEMPLATE_ID
}

You can test this endpoint at the following links.

For North America	For Europe
updateServiceCategory	updateServiceCategory

DELETE /serviceCategory/{serviceCategoryId}

Deletes the specified service category.

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The serviceCategoryId provided must be valid (exists).
The serviceCategoryId provided must belong to an active store that is associated with the Partner API key provided.
The store that the service category ID is associated with must be active (not disabled).
The merchantId provided must be valid and associated with an active store.

Notes

A category cannot be deleted if:
- A service is associated with it.
- It is a Head Office category template used in stores.

The above conditions can be ignored by setting the queryParam ignoreError to true. If so, the associated services will be moved into the default category.

Parameters

Parameter	Format	Description
serviceCategoryId	integer	The id of the service category

Request URL for North America

https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID

cURL

curl -X 'DELETE' \
'https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID' \
-H 'accept: application/json' \
  -H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY'

Successful Response

Here’s an example of a successful response.

{
"id": 12345,
"name": "Manicure",
"description": "All-in-one nail service.",
"profileImageUrl": "",
"merchantId": YOUR_MERCHANT_ID,
"isTemplate": false
}

You can test this endpoint at the following links.

For North America	For Europe
deleteServiceCategory	deleteServiceCategory

GET /serviceCategory/{serviceCategoryId}/moduleLink/{moduleId}

Retrieves the link configuration of a service category for a given integration module.

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The serviceCategoryId provided must be valid.
The serviceCategoryId provided must belong to an active store that is associated with the Partner API key provided.
The moduleId provided must be associated with the Partner API key provided.
The Partner API key must be authorized to be used for the provided moduleId.

Notes

If the link was never configured, a default service category link will be returned with empty values.

Parameters

Parameter	Format	Description
serviceCategoryId	integer	The id of the service category
moduleId	string	The id of the integration module the link is for.

Request URL for North America

https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_ID/moduleLink/YOUR_MODULE_ID

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory/YOUR_SERVICE_ID/moduleLink/YOUR_MODULE_ID

cURL

curl -X 'GET' \
'https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID/moduleLink/YOUR_MODULE_ID' \
-H 'accept: application/json' \
  -H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY'

Successful Response

Here’s an example of a successful response.

{
"link": {
  "serviceCategoryId": 12345,
  "moduleId": "YOUR_MODULE_ID",
  "externalId": "YOUR_EXTERNAL_ID",
  "metadata": {
    "classification": ""
  },
  "createdOn": "2024-11-08T22:00:47Z",
  "modifiedOn": "2024-11-08T22:00:47Z"
},
"serviceCategory": {
  "id": 12345,
  "name": "Nail Treatments",
  "description": "",
  "profileImageUrl": "",
  "merchantId": YOUR_MERCHANT_ID,
  "isTemplate": false,
  "serviceCategoryTemplateId": 56789
}
}

You can test this endpoint at the following links.

For North America	For Europe
getServiceCategoryModuleLink	getServiceCategoryModuleLink

PUT /serviceCategory/{serviceCategoryId}/moduleLink/{moduleId}

Updates the link configuration of a service category for a given integration module.

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The serviceCategoryId provided must be valid.
The serviceCategoryId provided must belong to an active store that is associated with the Partner API key provided.
The moduleId provided must be associated with the Partner API key provided.
The Partner API key must be authorized to be used for the provided moduleId.

Parameters

Parameter	Format	Description
serviceCategoryId	integer	The id of the service category
moduleId	string	The id of the integration module the link is for.

Request URL for North America

https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY/moduleLink/YOUR_MODULE_ID

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY/moduleLink/YOUR_MODULE_ID

cURL

curl -X 'PUT' \
'https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID/moduleLink/YOUR_MODULE_ID' \
-H 'accept: application/json' \
-H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"externalId": "YOUR_EXTERNAL_ID",
"metadata": {
  "classification": "supplemental"
}
}'

Successful Response

Here’s an example of a successful response.

{
"link": {
  "serviceCategoryId": 12345,
  "moduleId": "YOUR_MODULE_ID",
  "externalId": "YOUR_EXTERNAL_ID",
  "metadata": {
    "classification": "supplemental"
  },
  "createdOn": "2024-11-11T18:23:38Z",
  "modifiedOn": "2024-11-11T18:23:38Z"
},
"serviceCategory": {
  "id": 12345,
  "name": "Body Treatments",
  "description": "",
  "profileImageUrl": "",
  "merchantId": YOUR_MERCHANT_ID,
  "isTemplate": false,
  "serviceCategoryTemplateId": 56789
}
}

You can test this endpoint at the following links.

For North America	For Europe
updateServiceCategoryModuleLink	updateServiceCategoryModuleLink

GET /serviceCategory/{serviceCategoryId}/translations

Retrieves the translations of a specific service category.

*Note: Only the translations in the store's selected languages will be returned ("My Business" tab > Booking rules > Languages)

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The serviceCategoryId provided must belong to an active store that is associated with the Partner API key provided.

Parameters

Parameter	Format	Description
serviceCategoryId	integer	The id of the service category

Request URL for North America

https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID/translations

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID/translations

cURL

curl -X 'GET' \
'https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID/translations' \
-H 'accept: application/json' \
  -H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY'

Successful Response

Here’s an example of a successful response.

{
"translations": [
  {
    "language": "eng",
    "name": "Nail Treatments",
    "description": ""
  },
  {
    "language": "fre",
    "name": "Traitements pour ongles",
    "description": ""
  },
  {
    "language": "spa",
    "name": "Tratamientos de uñas",
    "description": ""
  }
]
}

You can test this endpoint at the following links.

For North America	For Europe
getServiceCategoryTranslations	getServiceCategoryTranslations

PUT /serviceCategory/{serviceCategoryId}/translations

Create or update the translations of a service category.

*Note: Only the translations for the languages provided in the request will be created/updated ("My Business" tab > Booking rules > Languages)

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid.

Requirements & Specifications

The serviceCategoryId provided must belong to an active store that is associated with the Partner API key provided.

Parameters

Parameter	Format	Description
serviceCategoryId	integer	The id of the service category

Request URL for North America

https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID/translations

Request URL for Europe

https://api.booxi.eu/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID/translations

cURL

curl -X 'PUT' \
'https://api.booxi.com/booking/v1/serviceCategory/YOUR_SERVICE_CATEGORY_ID/translations' \
-H 'accept: application/json' \
-H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"translations": [
  {
    "language": "eng",
    "name": "Nail Treatments",
    "description": ""
  },
  {
    "language": "fre",
    "name": "Traitements pour les ongles",
    "description": ""
  },
  {
    "language": "spa",
    "name": "Tratamientos de las uñas",
    "description": ""
  }
]
}
'

Successful Response

Here’s an example of a successful response.

{
"translations": [
  {
    "language": "eng",
    "name": "Nail Treatments",
    "description": ""
  },
  {
    "language": "fre",
    "name": "Traitements pour les ongles",
    "description": ""
  },
  {
    "language": "spa",
    "name": "Tratamientos de las uñas",
    "description": ""
  }
]
}

You can test this endpoint at the following links.

For North America	For Europe
updateServiceCategoryTranslations	updateServiceCategoryTranslations

Error Codes

Code	Conditions
400	Request data is wrong (ex: characters provided are not integers)
401	Partner API Key is not found.
	Partner API Key is invalid.
403	Forbidden
404	Provided serviceCategoryId is associated with a disabled store (status = -1)
	No service category record found for provided serviceCategoryId.
	Service category is already deleted.
	Unexpected error

Limitations & Notes

This API shall not be used to generate reports or export data.
Modules must be configured and activated by Booxi before usage.

How to retrieve client records using the Booxi API

How to use the Client API

How to use the STAFF API

How to use the Service API

How to manage store and staff schedules using the Booxi API