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

Retrieving a client’s booking history can be useful in different cases, whether it be to provide clients access to their booking history or in a clienteling application as a way for your staff to review a client's past and upcoming bookings.

Retrieving a Client’s Booking History

To retrieve a client’s booking history, use the GET /booking?clientId={clientId}/ API. Your request must minimally include a starting and ending date and a valid clientId. Optional parameters are available to further filter out the results.

When querying a client’s booking history, the client id must belong to a clientele that is associated with a merchant that is accessible with your partner API key.

Mandatory Parameters

Parameter	Format	Description
from	from={from} from=2022-01-01T00:00:00Z	Starting date in RFC3339 format.
to	to={to} to=2022-12-31T00:00:00Z	Ending date in RFC3339 format.
clientId	clientId={clientId} clientId=1111	Client Id the query should be performed for.

Request URL for North America

https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}

cURL

curl -X GET 
"https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}" 
-H  "accept: application/json"
-H  "Booxi-PartnerKey: YOUR_PARTNER_KEY"

Request URL for Europe

https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}

cURL

curl -X GET 
"https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}" 
-H  "accept: application/json"
-H  "Booxi-PartnerKey: YOUR_PARTNER_KEY"

Optional Parameters

Parameter	Format	Description
merchantId	merchantId={merchantId} merchantId=31386	Limit bookings assigned to a given merchant.
bookingMethod	bookingMethod={type} bookingMethod=Appointment	Limit bookings to a specific type. Supported values are: Appointment Reservation Default to all types.
order	order={order} order=ascending	List results in ascending or descending order. Supported values are: ascending descending
language	language={language} language=eng	Choose what language the results will be provided in. The code must be in ISO 639-3 format except for French which uses “fre”. The language is used for ready-only properties of an object that are generated by Booxi, localizable properties (ex: service name) and certain errors. Defaults to the authenticated merchant's preferred language. The API also accepts ISO 639-1 and ISO 639-2 codes. See here for the list of supported languages.

Example with all parameters:

Request URL for North America

https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}&merchantId={merchantId}&bookingMethod={type}&order={order}&language={language}

cURL

curl -X GET 
"https://api.booxi.com/booking/v1/booking?from={from}&to={to}&clientId={clientId}&merchantId={merchantId}&bookingMethod={type}&order={order}&language={language}" 
-H  "accept: application/json"
-H  "Booxi-PartnerKey: YOUR_PARTNER_KEY"

Request URL for Europe

https://api.booxi.eu/booking/v1/booking?from={from}&to={to}&clientId={clientId}&merchantId={merchantId}&bookingMethod={type}&order={order}&language={language}

cURL

curl -X GET 
"https://api.booxi.eu/booking/v1/booking?from={from}&to={to}&clientId={clientId}&merchantId={merchantId}&bookingMethod={type}&order={order}&language={language}" 
-H  "accept: application/json"
-H  "Booxi-PartnerKey: YOUR_PARTNER_KEY"

You can test this API at the following links:

North America	Europe
findBooking	findBooking

Successful JSON Response

When the query is successful, the response will include a list of all bookings that meet the query’s criteria. Note that the response also contains a list of group events, services, staff and merchant objects that are referred to by ID in the booking object. That extra data isn’t unique to the booking object.

Response Fields	Description
bookings	Array of bookings that meet the query’s criteria. The booking object contains the same information as used in bookings created via the API.
groupEvents	Array of group events referenced in the bookings.
services	Array of all services provided in the bookings.
staff	Array of all staff referenced in the bookings.
merchants	Array of all merchants referenced in the bookings.

Here’s an example of a successful response:

{
  "bookings": [
    {
      "bookingId": "A00001234",
      "merchantId": 100,
      "bookingMethod": "Appointment",
      "status": "Approved",
      "isCompleted": false,
"acquisitionChannel": "e-commerce",
      "startsOn": "2020-10-01T14:00:00Z",
      "totalClientTimespan": {
        "start": "2020-01-04T12:00:00Z",
        "end": "2020-01-04T12:45:00Z",
        "duration": 45
      },
      "staffId": 582,
      "staffFirstName": "Jane",
      "staffLastName": "Poe",
      "items": [
        {
          "serviceId": 1001,
          "serviceName": "French Cooking Tutorial",
          "serviceHasAssociatedResources": true,
          "resourceId": 15,
          "resourceName": "Room #15",
          "price": {
            "visibility": "Show",
            "amount": "10.00",
            "amountPerPerson": "5.99",
            "amountPerHour": "0.00",
            "currency": "USD",
            "isStartingAt": false,
            "tax": "Excluded"
          },
          "reservedClientTimespan": {
            "start": "2020-01-04T12:00:00Z",
            "end": "2020-01-04T12:45:00Z",
            "duration": 45
          },
          "shoppingCartProductId": "ID-199"
        }
      ],
      "location": "Business",
      "locationText": "",
      "client": {
        "id": 1901,
        "firstName": "Emilie",
        "lastName": "Authier",
        "email": "emilie.authier@booxi.com",
        "homePhoneNumber": "+15552346789",
        "mobilePhoneNumber": "+15552346789",
        "presence": "Expecting",
        "remindByEmail": true,
        "remindBySMS": true,
        "additionalRequest": "Can we bring our own ingredients?"
      },
      "payment": {
        "total": "10.99",
        "paid": "0.00",
        "onlinePaymentId": "P000123",
        "onlinePaymentAmount": "2.00",
        "onlinePaymentStatus": "Requested"
      },
      "createdOn": "2020-01-01T07:15:00Z",
      "createdBy": "Staff",
      "modifiedOn": "2020-01-01T07:30:00Z",
      "modifiedBy": "Staff"
    }
  ],
  "groupEvents": [
    {
      "id": 1,
      "start": "2017-06-29T09:00:00Z",
      "duration": 30,
      "price": {
        "visibility": "Show",
        "amount": "10.00",
        "amountPerPerson": "5.99",
        "amountPerHour": "0.00",
        "currency": "USD",
        "isStartingAt": false,
        "tax": "Excluded"
      },
      "location": "Business",
      "locationText": "",
      "staffId": 1,
      "staffName": "string",
      "staffFirstName": "Sample",
      "staffLastName": "Employee",
      "staff": {
        "id": 1,
        "name": "Jane Poe",
        "firstName": "Jane",
        "lastName": "Poe",
        "position": "Manager",
        "biography": "The friendly manager.",
        "profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQX.png",
        "timeSelectionMode": "ServiceTimeSelection"
      },
      "serviceId": 1,
      "serviceName": "Sample Service",
      "serviceCategoryId": 0,
      "serviceCategoryName": "Main Services",
      "service": {
        "id": 1,
        "merchantId": 1,
        "name": "Self Printing",
        "tags": "promotion,self-service",
        "duration": 30,
        "showDuration": true,
        "hasDurationCustomization": false,
        "bookingMethod": "Appointment",
        "location": "Business",
        "locationText": "",
        "price": {
          "visibility": "Show",
          "amount": "10.00",
          "amountPerPerson": "5.99",
          "amountPerHour": "0.00",
          "currency": "USD",
          "isStartingAt": false,
          "tax": "Excluded"
        },
        "hasPriceCustomization": false,
        "categoryId": 0,
        "categoryName": "Main Services",
        "description": "Enjoy using all of our equipment at your leisure.",
        "profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQB.png",
        "staffSelectionMode": "AssignedStaff",
        "timeSelectionMode": "TimeSlot",
        "maxReservationSize": 0,
        "bookingPolicy": "Any modification or cancellation must be done at least 24 h before       
                          the appointment time.",
        "instructions": "Please arrive 10 minutes before the start of your appointment.",
        "metadata": {
          "classification": "supplemental"
        },
        "surveyModel": {
          "pages": {
            "name": "default",
            "elements": [
              {
                "type": "text",
                "name": "Q1",
                "title": "Is this your first time here?"
              }
            ]
          }
        }
      },
      "attendeeCount": 3,
      "attendeeCapacity": 8,
      "isCompleted": false,
      "onlineBookingAllowedFrom": "2017-06-22T04:00:00Z",
      "onlineBookingAllowedUntil": "2017-06-28T09:00:00Z",
      "createdOn": "2017-06-20T15:42:13Z",
      "metadata": {
        "classification": "supplemental"
      }
    }
  ],
  "services": [
    {
      "id": 1,
      "merchantId": 1,
      "name": "Self Printing",
      "tags": "promotion,self-service",
      "duration": 30,
      "showDuration": true,
      "hasDurationCustomization": false,
      "bookingMethod": "Appointment",
      "location": "Business",
      "locationText": "",
      "price": {
        "visibility": "Show",
        "amount": "10.00",
        "amountPerPerson": "5.99",
        "amountPerHour": "0.00",
        "currency": "USD",
        "isStartingAt": false,
        "tax": "Excluded"
      },
      "hasPriceCustomization": false,
      "categoryId": 0,
      "categoryName": "Main Services",
      "description": "Enjoy using all of our equipment at your leisure.",
      "profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQB.png",
      "staffSelectionMode": "AssignedStaff",
      "timeSelectionMode": "TimeSlot",
      "maxReservationSize": 0,
      "bookingPolicy": "Any modification or cancellation must be done at least 24 h before
                        the appointment time.",
      "instructions": "Please arrive 10 minutes before the start of your appointment.",
      "metadata": {
        "classification": "supplemental"
      },
      "surveyModel": {
        "pages": {
          "name": "default",
          "elements": [
            {
              "type": "text",
              "name": "Q1",
              "title": "Is this your first time here?"
            }
          ]
        }
      }
    }
  ],
  "staff": [
    {
      "id": 1,
      "merchantId": 1,
      "name": "Self Printing",
      "tags": "promotion,self-service",
      "duration": 30,
      "showDuration": true,
      "hasDurationCustomization": false,
      "bookingMethod": "Appointment",
      "location": "Business",
      "locationText": "",
      "price": {
        "visibility": "Show",
        "amount": "10.00",
        "amountPerPerson": "5.99",
        "amountPerHour": "0.00",
        "currency": "USD",
        "isStartingAt": false,
        "tax": "Excluded"
      },
      "hasPriceCustomization": false,
      "categoryId": 0,
      "categoryName": "Main Services",
      "description": "Enjoy using all of our equipment at your leisure.",
      "profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQB.png",
      "staffSelectionMode": "AssignedStaff",
      "timeSelectionMode": "TimeSlot",
      "maxReservationSize": 0,
      "bookingPolicy": "Any modification or cancellation must be done at least 24 h before 
                        the appointment time.",
      "instructions": "Please arrive 10 minutes before the start of your appointment.",
      "metadata": {
        "classification": "supplemental"
      },
      "surveyModel": {
        "pages": {
          "name": "default",
          "elements": [
            {
              "type": "text",
              "name": "Q1",
              "title": "Is this your first time here?"
            }
          ]
        }
      }
    }
  ],
  "merchants": [
    {
      "id": 1,
      "name": "The Work Shop",
      "isAvailableOnline": true,
      "storeNumber": "US1210",
      "groupId": 201,
      "groupName": "Printing Co",
      "groupCategoryId": 30,
      "groupCategoryName": "Manhattan",
      "address": {
        "street": "123 Fake St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      },
      "contactFirstName": "Jane",
      "contactLastName": "Poe",
      "phoneNumber": "+15553334444",
      "email": "jane@example.com",
      "tags": "self-service,open-late",
      "websiteUrl": "",
      "bookingUrl": "https://site.booxi.com/theworkshop?lang=eng",
      "apiKey": "7L9K7N2QrELXYJ8PJBsAtSA7HuL3BgRs",
      "description": "The Work Shop is a great place to find and buy work supplies.",
      "coverImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQY.png",
      "profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQZ.png",
      "currency": "USD",
      "tax1Name": "CST",
      "tax1Rate": "0.0450",
      "tax2Name": "",
      "tax2Rate": "0",
      "timeZone": "America/New_York",
      "latitude": "40.6892361",
      "longitude": "-74.0445726",
      "defaultLanguage": "eng",
      "openHours": [
        {
          "dow": 1,
          "start": "09:00:00",
          "end": "13:45:00"
        }
      ]
    }
  ],
  "resources": [
    {
      "id": 1001,
      "name": "Room 1",
      "description": "This is a giant resource.",
      "status": "Active"
    }
  ],
  "cursor": "string"
}

Limitations

The authentication method requires a secure environment.
The endpoint must not be exposed on a webpage; instead, it should be handled server-side.
The client booking history does not include rental bookings.
The client booking history does not include unscheduled appointments.

How to Build a Custom Booking Process Using the API

How to retrieve client records using the Booxi API

How to retrieve a client’s metadata using the Booxi API

How to create a booking using the Booxi API

How to use the GET /calendar endpoint

How to Retrieve a Client's Booking History Using the Booxi API

Retrieving a Client’s Booking History

Mandatory Parameters

Optional Parameters

Successful JSON Response

Limitations