Knowledge Base

Webhooks & APIs

Use Cases

How to Use the SERVICE CATEGORY API

The following article provides an overview of the Service Category 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

GET /serviceCategory/list
POST /serviceCategory
GET /serviceCategory/{serviceCategoryId}
PUT /serviceCategory/{serviceCategoryId}
DELETE /serviceCategory/{serviceCategoryId}
GET /serviceCategory/{serviceCategoryId}/moduleLink/{moduleId}
PUT /serviceCategory/{serviceCategoryId}/moduleLink/{moduleId}
GET /serviceCategory/{serviceCategoryId}/translations
PUT /serviceCategory/{serviceCategoryId}/translations

GET /serviceCategory/list

Find service categories of a given merchant, 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 merchant.
The service categories found by externalId must be associated with a merchant 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 merchant.

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 merchant 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 merchant 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 merchant that is associated with the Partner API key provided.
The merchant that the service category ID is associated with must be active (not disabled).
The merchantId provided must be valid and associated with an active merchant.

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 merchant 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 merchant 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 merchant 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 merchant 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 merchant 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.
401	Partner API Key is invalid.
403	Forbidden
404	Provided serviceCategoryId is associated with a disabled merchant (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.

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.