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.

This API is not made to perform data replication by calling it on a frequent basis to update an external database. For such a purpose, the webhook should be employed.
Note that this implementation requires a partner API Key. If you haven’t been provided with such a key, please contact your Booxi representative.

Remember that the URL to use depends on your hosting region. This article presents examples from a North American hosting.

North America	Europe
api.booxi.com	api.booxi.eu

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.

References

For more information about Booxi APIs and their usage, refer to the following links:

Europe: https://api.booxi.eu/doc/booking.html

Americas: https://api.booxi.com/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 must be requested to your Booxi Account Manager. The Partner API key must only be used in server-side (backend) code to keep it a secret.

Understand how clients book appointments

Understand how time zones work in Booxi

How to disable online booking

Business booking rules

Track online booking usage with Google Analytics 4 (Booking widget v3)