Knowledge Base

Webhooks & APIs

Use Cases

How to use the SERVICE API

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
GET /service/{serviceId}
GET /service/list
GET /service/{serviceId}/translations
PUT /service/{serviceId}/translations
PUT /service/{serviceId}
DELETE /service/{serviceId}

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
createService	createService

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
getService	getService

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
getServiceList	getServiceList

PUT /service/{serviceId}/translations

Updates the translations of a 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).

Notes

Only the translations provided in the request will be created/updated. The other translations will remain unchanged.
Translations can only be created/updated for the merchant's supported languages (to consult the list of languages, go to the "My Business" tab > Booking rules > Languages)
Updating the translation in the merchant default language will also update the service information.
If the provided service's booking survey is set to "None" or "Complex" and values are entered for the surveyText field, a 400 error will occur; the surveyText field can only be entered if the service's booking survey is not set to "None" or "Complex".

Parameters

Parameter	Format	Description
serviceId	integer	The id of the service.

Request URL for North America

https://api.booxi.com/booking/v1/service/YOUR_SERVICE_ID/translations

Request URL for Europe

https://api.booxi.eu/booking/v1/service/YOUR_SERVICE_ID/translations

cURL

curl -X 'PUT' \
  'https://api.booxi.com/booking/v1/service/YOUR_SERVICE_ID/translations' \
  -H 'accept: application/json' \
  -H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "translations": [
    {
      "language": "eng",
      "name": "Haircut",
      "instructions": "",
      "description": "",
      "surveyText": ""
    },
    {
      "language": "fre",
      "name": "Coupe de cheveux",
      "instructions": "",
      "description": "",
      "surveyText": ""
    },
  {
      "language": "spa",
      "name": "Corte de pelo",
      "instructions": "",
      "description": "",
      "surveyText": ""
    }
  ]
}'

Successful Response

Here’s an example of a successful response.

    {
  "translations": [
    {
      "language": "eng",
      "name": "Haircut",
      "instructions": "",
      "description": "",
      "surveyText": ""
    },
    {
      "language": "fre",
      "name": "Coupe de cheveux",
      "instructions": "",
      "description": "",
      "surveyText": ""
    },
    {
      "language": "spa",
      "name": "Corte de pelo",
      "instructions": "",
      "description": "",
      "surveyText": ""
    }
  ]
}

You can test this endpoint at the following links.

For North America	For Europe
updateServiceTranslations	updateServiceTranslations

GET /service/{serviceId}/translations

Retrieves the translations of a service. Only the translations in the merchant selected languages will be returned (see "My Business" tab > Booking rules > Languages).

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

https://api.booxi.com/booking/v1/service/YOUR_SERVICE_ID/translations

Request URL for Europe

https://api.booxi.eu/booking/v1/service/YOUR_SERVICE_ID/translations

cURL

curl -X 'GET' \
  'https://api.booxi.com/booking/v1/service/YOUR_SERVICE_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": "Manicure",
      "instructions": "Make sure to bring all the necessary equipment to the appointment.",
      "description": "Full manicure: full service and cleaning included",
      "surveyText": ""
    },
    {
      "language": "fre",
      "name": "Manucure",
      "instructions": "Assurez-vous d'apporter tout équipement nécessaire.",
      "description": "Manucure complet : service et nettoyage inclus",
      "surveyText": ""
    }
  ]
}

You can test this endpoint at the following links.

For North America	For Europe
getServiceTranslations	getServiceTranslations

PUT /service/{serviceId}

Updates the specified service.

Permissions & Security

A Partner API key is required.
The Partner API key provided must be valid for access to be granted to this endpoint.
The service ID provided must belong to a merchant that is associated with the Partner API key provided.
The merchant that the service ID is associated with must be active (i.e. not disabled)

Requirements & Specifications

The merchantId provided must be valid.
The merchantId provided must be associated with an active merchant.
The serviceId provided must be valid (and not deleted)

Notes

Properties not included in the request body will be left unchanged.
Properties included in the request body will override existing values, even when blank (exception: "name" cannot be blank).
The following properties can be updated:
- name (cannot be blank)
- status
- tags
- description
- instructions
- isSurveyRequired
- surveyText
- surveyType
- rentalReturnMode (only for services of type "Rental")
- duration
- showDuration
- location (must be valid for the bookingMethod)
- locationText (applies to services whose location is set to "Videoconference" or "Phone")
- price
- categoryId
- maxReservationSize (only for GroupReservation services)
The following properties cannot be updated:
- id
- bookingMethod
- merchantId
- profileImageUrl
- metadata
- createdOn
- modifiedOn
- serviceTemplateId
- isTemplate
- surveyModel
- hasDurationCustomization
- hasPriceCustomization
- categoryName
- staffSelectionMode
- timeSelectionMode
- bookingPolicy

Parameters

Parameter	Format	Description
serviceId	integer	The id of the service

Request URL for 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 'PUT' \
  'https://api.booxi.com/booking/v1/service/YOUR_SERVICE_ID' \
  -H 'accept: application/json' \
  -H 'Booxi-PartnerKey: YOUR_PARTNER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "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.",
  "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": YOUR_SERVICE_ID,
  "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": {},
  "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-06-12T19:33:55Z",
  "modifiedOn": "2024-10-10T14:06:47Z"
}

You can test this endpoint at the following links.

For North America	For Europe
updateService	updateService

DELETE /service/{serviceId}

Deletes the specified service.

Permissions & Security

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

Requirements & Specifications

The merchant that the service ID is associated with must be active (not disabled).
The serviceId provided must be valid (and not deleted).
The serviceId provided must be associated with a merchant that is accessible with the provided Partner API key.

Parameters

Parameter	Format	Description
serviceId	integer	The id of the service.

Request URL for North America

https://api.booxi.com/booking/v1/service/SERVICE_ID

Request URL for Europe

https://api.booxi.eu/booking/v1/service/SERVICE_ID

cURL

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

Successful Response

Here’s an example of a successful response.

{
  "id": 370524,
  "merchantId": 11359,
  "name": "Pedicure",
  "tags": "",
  "duration": 60,
  "showDuration": true,
  "hasDurationCustomization": false,
  "bookingMethod": "Appointment",
  "location": "Business",
  "locationText": "",
  "price": {
    "visibility": "Show",
    "amount": "10.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": {},
  "isSurveyRequired": false,
  "surveyText": "",
  "surveyType": "None",
  "status": "Offline",
  "isTemplate": false,
  "createdOn": "2024-06-12T21:02:28Z",
  "modifiedOn": "2024-08-12T21:12:36Z"
}

You can test this endpoint at the following links.

For North America	For Europe
deleteService	deleteService

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.