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

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.

 

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

---

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.