By the end of this guide, you will be able to:

Identify the use cases that Booxi supports in a clienteling context.
Choose the recommended integration approach for each scenario.
Locate the available API endpoints for each use case.
Follow clear implementation guidelines for each use case.

Booxi's recommendations:

Use Booxi as the authoritative source for appointment data to maximize reliability:
- Use the Booxi API to fetch the calendar of events (group events and appointments).
- Use the Booxi API to fetch a client's appointment and group event reservation history.
Use the Booxi Head Office to provision services using service templates.

Requirements

You must have active Booxi accounts and access to a Booxi Partner API key.
You must have determined whether your integration will use the Booxi API alone or in combination with a connector to a CRM.

Use Cases

This guide covers the following clienteling app use cases related to appointment booking.

View a client's booking history

View the booking history of any client directly within the clienteling app.

View a staff event calendar

View your own calendar of events, including appointments and scheduled group events.
As a manager, view each staff member's event calendar, including appointments and scheduled group events.

Book a new appointment

Book a new appointment for a client on behalf of any staff member.

Manage appointments

Edit or reschedule an existing appointment in your calendar, including changing its status to cancelled, no-show, client arrived, or completed.
As a manager, edit or reschedule an existing appointment in any staff calendar, including changing its status.
As a manager, dispatch appointment requests to staff.

Modify appointment details

Edit an existing appointment's details, including client request, quick note, and services.

Book without retaining personal data

Book an appointment for a customer without retaining their personal information beyond what is required for the sole purpose of that appointment.

*Note: The scheduling of resources (rooms, equipment) is not covered in this guide.

Sample implementation

Here's a look at an example of a clienteling app implementation:

Relevant endpoints

The table below lists all endpoints required for a clienteling app integration. Additional endpoints are available in the Booxi API reference.

Endpoint	Description	Reference
GET /booking/{bookingId}	Retrieve a single booking.	View
GET /booking	Find bookings for a given client ID and date range (e.g., to retrieve booking history).	View
POST /booking	Create a new booking (appointment or reservation).	View
PUT /booking/{bookingId}	Update an existing booking: change status, reschedule, or modify details.	View
GET /calendar	Retrieve events (bookings and timeslots) from a specific staff calendar.	View
GET /merchant	Retrieve store information.	View
GET /merchant/list	Retrieve the list of all stores in a merchant group or country.	View
GET /staff/list	Retrieve the staff list for a store, or find a staff member by moduleLink external ID.	View
GET /service	Retrieve online services for a store, optionally filtered by staff ID.	View
GET /service/list	Retrieve the full service list for a store regardless of online status, or find a service by moduleLink external ID.	View
GET /serviceCategory GET /serviceCategory/list	Retrieve the list of service categories for a given store.	View
GET /service/{serviceId}/availability	Retrieve real-time availability for a service, for a specific staff member or all staff offering it.	View
POST /availability/search	Search for available time slots or ranges for a set of services (i.e. for multi-service booking).	View
GET /client	Find a client using matching criteria, including a moduleLink external ID.	View
POST /client	Create a new client and retrieve the client ID for use in booking.	View
PUT /client/{clientId}/moduleLink	Update the moduleLink external ID of a Booxi client to link it with your CRM client ID.	View

Creating a New Booking

Use the Booxi API endpoints to present an appointment form in your clienteling app and allow staff to book appointments directly in Booxi.

Prerequisites

A merchant ID (store) in which the appointment will be booked.
A staff ID identifying the calendar in which the appointment will be booked.
A service ID for the service being booked.
A client ID is optional — Booxi will attempt to find a match based on name and email, or name and phone number, and will create a new client if no match is found. You may also find or create a client beforehand and link them to your CRM customer ID using moduleLink.

Required Endpoints

Endpoint	Description	Reference
GET /merchant	Retrieve the merchant ID if it is not already known.	View
GET /staff	Retrieve the list of store staff who are available online and have calendars.	View
GET /service/list	Retrieve the list of services offered by the store.	View
POST /booking	Create the appointment.	View

Optional Endpoints

Endpoint	Description	Reference
GET /merchant/list	Retrieve all stores in a merchant group and match an external store number to a merchant ID.	View
GET /serviceCategory	Display services organized by category.	View
GET /service	Retrieve services available online, optionally filtered by staff ID.	View
GET /client	Find a client matching a moduleLink external ID (e.g., your CRM customer ID).	View
POST /client	Create a new client in Booxi.	View
GET /staff/list	Find a staff member by moduleLink external ID; returns staff regardless of status.	View
GET /service/{serviceId}/availability	Retrieve availability for a service, optionally filtered by staff ID.	View
POST /availability/search	Search for available time slots or ranges for a set of services (i.e. for multi-service booking).	View

Steps

Find the merchant ID using GET /merchant. You can also match an external store number using GET /merchant/list.
Find the client in Booxi using your CRM customer ID via GET /client (see sequence diagram below), unless the Booxi client ID is already stored in your clienteling app. You can also search by name, email, and phone number.
If no CRM match is found, either post the booking without a client ID, or create the client first:
1. Create the client using POST /client.
2. Link your CRM customer ID using PUT /client/moduleLink, or listen to the Booxi appointment.created webhook event and set the CRM customer ID at that point.
Retrieve the staff list using GET /staff, or find a specific staff member by moduleLink external ID (e.g., employee ID) using GET /staff/list.
Retrieve the service list using GET /service, optionally filtered by staff ID. Alternatively, use GET /service/list to find a service by moduleLink external ID (e.g., product ID). This endpoint also returns services regardless of their online or booking-enabled status.
Retrieve staff availability for the selected service using GET /service/{serviceId}/availability or, if the booking contains multiple services, use POST /availability/search to find availability for the set of services.
Create the client using POST /client.
Create the appointment using POST /booking with the merchant ID, service ID, staff ID, selected time slot, and optionally the client ID.
Booxi will send a webhook event for the new appointment.

*Note: GET /staff returns only staff members who have a calendar and are available online. It supports filtering by service ID. GET /service returns only services available online. It supports filtering by staff ID. GET /serviceCategory is also available to retrieve all service categories.

Finding or Creating a New Client to Book an Appointment

Updating an Existing Booking

This section covers how to update an appointment status, reschedule, or modify details. It focuses on appointments; the same PUT /booking endpoint also handles cancelling group event reservations.

Prerequisite

You need a booking ID.

Required Endpoints

Endpoint	Description	Reference
GET /booking	Retrieve the appointment.	View
PUT /booking/{bookingId}	Update the appointment: change status, reschedule, or modify details.	View

Optional Endpoints

Endpoint	Description	Reference
GET /calendar	Retrieve a staff member's appointment calendar.	View
GET /booking	Retrieve a client's booking history.	View

Steps

Retrieve the appointment from Booxi using GET /booking, supplying either:
1. A booking ID returned by GET /calendar (staff event calendar) or GET /booking (client booking history).
2. A booking ID stored in an external calendar event.
To change service, staff, or time, follow the same steps described in the Creating a New Booking section to fetch services, staff, and availabilities.
Update the appointment using PUT /booking:
1. Change the status: cancelled, approved, or completed.
2. Change the presence: expecting, arrived, or no-show.
3. Reschedule: assign a new staff member, date, and time.
4. Modify details: services, duration, price, client request, or quick note.
Booxi will send a webhook event for the updated appointment.

Retrieving an Existing Booking

Prerequisite

You need a booking ID.

Required Endpoint

Endpoint	Description	Reference
GET /booking/{bookingId}	Retrieve an appointment.	View

Optional Endpoints

Endpoint	Description	Reference
GET /calendar	Retrieve a staff member's appointment calendar.	View
GET /booking	Retrieve a client's booking history.	View

Steps

Retrieve the appointment using GET /booking:
1. Using the booking ID returned by GET /calendar (staff event calendar) or GET /booking (client booking history).
2. Using a booking ID stored in an external calendar.

Accessing a Client's Booking History

Use the Booxi API to access the booking history (appointments and group event reservations) for a client and display them in the client view of your clienteling app.

Prerequisites

A client ID for whom you want to see the booking history.
A date range within which to find bookings.

Required Endpoint

Endpoint	Description	Reference
GET /booking	Find bookings using the client ID.	View

Optional Endpoints

Endpoint	Description	Reference
GET /merchant/list	Retrieve the merchant ID of a store.	View
GET /client	Find a client matching a moduleLink external ID (e.g., your CRM customer ID).	View

Steps

Find the merchant ID using GET /merchant, or match an external store number using GET /merchant/list.
Find the client in Booxi using your CRM customer ID with GET /client, unless the Booxi client ID is already stored in your clienteling app. You can also search by name, email, and phone number.
Call GET /booking with the Booxi client ID and a from/to date range:
1. Optionally specify a merchant ID to retrieve only bookings made at a specific store.
2. Optionally set bookingMethod to Appointment to retrieve appointment bookings only.
3. Optionally specify an Order to receive results in ascending or descending chronological order.
If the response includes a cursor, call the endpoint again with that cursor to retrieve subsequent pages, and continue until no cursor is returned.

Accessing a Staff Member's Event Calendar

Use the Booxi API to access the bookings (appointments, group events, and timeslots) for a staff calendar and display a calendar view in your clienteling app.

Prerequisites

A staff ID for whom you want to see the calendar events.
A date range within which to find bookings.

Required Endpoint

Endpoint	Description	Reference
GET /calendar	Retrieve events using the staff ID.	View →

Optional Endpoints

Endpoint	Description	Reference
GET /staff/list	Find the Booxi staff ID of a staff member from their moduleLink external ID (e.g., employee ID).	View

Steps

Retrieve the Booxi staff ID if you do not already have it:
1. Find the merchant ID using GET /merchant, or use GET /merchant/list to match an external store number.
2. Retrieve the staff list for the merchant ID using GET /staff/list.
3. Find the staff member using their external moduleLink (user or employee ID) with GET /staff/list. Provide your module ID and external employee or user ID, then store the returned Booxi staff ID.
Retrieve the event calendar using GET /calendar with the Booxi staff ID and from/to dates:
1. Use the eventType parameter to filter by Appointment, GroupEvent, or TimeSlot.
2. Use the include parameter to request full detail objects: Appointment, GroupEvent, TimeSlot, Service, Staff.
If the response includes a cursor, call the endpoint again with that cursor to retrieve subsequent pages, and continue until no cursor is returned.

*Note: You can also schedule and manage timeslots (for extra availability, busy tasks, or syncing with an external calendar) using the TimeSlot endpoints in the Booxi API reference.

Sync Your CRM Customers with Booxi Clients

A CRM solution is often used as the central source of client information. The most common pattern is to create new clients in the CRM first and then provision other solutions — rather than adapting each solution to source clients from the CRM. This section therefore focuses on client information synchronization.

In some cases, a client may be created first at the time of online booking. In these situations, a webhook allows you to capture the new client creation and link it to your CRM.

ModuleLink

Booxi provides a concept of external modules, allowing each client to have a linked representation in third-party solutions such as a CRM. Each client moduleLink stores an external customer ID and associated metadata. ModuleLink is also available for staff, services, and stores.

Integration options:

If you do not store a Booxi client reference: use GET /client to find a Booxi client associated with an external customer ID via their moduleLink.
If you use an ETL pipeline: use POST, PUT, and DELETE /client to manage client updates. Use GET/PUT /client/moduleLink to retrieve and update the link.
If you use a connector: listen to the third-party solution's webhook and update Booxi using the API calls described in the ETL approach above.
If you use the Booking Widget to create new clients: the widget allows you to pass your CRM customer ID at the time of booking when a CRM module is configured in Booxi.

Available Endpoints

Endpoint	Description	Reference
GET /client/{clientId}	Retrieve a client.	View
GET /client	Find a client by external customer ID, name, phone, or email.	View
POST /client	Create a new client.	View
PUT /client/{clientId}	Update an existing client.	View
DELETE /client/{clientId}	Delete an existing client.	View
GET /client/{clientId}/moduleLink/{moduleId}	Read the external ID and metadata associated with a client for a specific module (e.g., my_crm_name).	View
PUT /client/{clientId}/moduleLink/{moduleId}	Replace the external ID and metadata associated with a client for a specific module (e.g., my_crm_name).	View

Using the Booking Widget to Pass Your CRM Customer ID

Use the Booxi Booking Widget with an external customer ID from an existing customer's web session.

Prerequisites

You must have integrated the Booking Widget on your website using a valid Merchant API key.
You must be able to obtain your CRM customer ID.
A module ID (e.g., your_crm_module) must be configured in Booxi and set as the primary customer module for each store.

Steps

Integrate the Booking Widget on your website following this guide.
Retrieve your CRM customer ID and include it in the ClientData object provided to the Booking Widget.
When a booking is made:
1. If a match is found in Booxi, the booking will be created using the matched Booxi client.
2. If no match is found, a new Booxi client will be created and the provided CRM customer ID will be associated as a moduleLink for the configured primary customer module.
Booxi will send a webhook event for the new appointment. If the CRM customer ID was set, it will be included in the webhook payload.

Code Example

<button onclick="BookNow.open({
  apiKey: 'YOUR_API_KEY_HERE',
  client: {
    firstName: 'John',
    lastName: 'Smith',
    email: 'john.smith@example.org',
    mobilePhoneNumber: '+17219992437',
    customerId: 'CUSTOMER-123',
    skipClientForm: false
  }
})">Book Now</button>

References

Booking Widget Implementation Guide (v3)

Using the Webhook to Link Your CRM Customer ID to Booxi Clients

Use the Booxi webhook and API endpoints to link Booxi clients to an external CRM.

Prerequisites

A module ID (e.g., your_crm_module) must be configured in Booxi.
A webhook callback URL and a Partner API key configured by Booxi.

Required Endpoint

Endpoint	Description	Reference
PUT /client/{clientId}/moduleLink/{moduleId}	Update the client's moduleLink using the client ID.	View

Steps

Listen to the appointment.created and appointment.updated webhook events (and reservation events if needed).
For each event, check whether a clientLink record exists for your module ID:
1. Look in content.booking.client to identify the Booxi client ID.
2. Find the matching entry in content.clientLinks (where content.booking.client.id = content.clientLinks[0].clientId) to determine whether the client is already linked to your CRM. The matching entry should contain your CRM module ID (e.g., my_crm_module) and an externalId.
If no link exists:
1. Find a matching customer in your CRM, or create a new one.
2. Use PUT /client/moduleLink to update the Booxi client's moduleLink, providing the Booxi client ID, your module ID, and your CRM customer ID.

Webhook content.clientLinks Example

"clientLinks": [
  {
    "clientId": 10374296,
    "moduleId": "your_crm_module",
    "createdOn": "2024-11-19T19:43:45Z",
    "externalId": "CUSTOMER-123",
    "modifiedOn": "2024-11-19T19:43:45Z"
  }
]

References

Personal Data and Consents

When capturing personally identifiable information (PII), the customer's consent is required to process and store that data.

For PII captured through the Booxi Booking Widget, the customer must consent to your terms and conditions and privacy policy before the booking is completed. This consent permits you to process and retain the data.
For PII captured when booking an appointment via the Booxi API, you are responsible for managing consent. If no explicit consent is given by the customer, an implicit consent applies solely for the purpose of completing the booking transaction. You may retain that PII for a reasonable period of time that serves that purpose.

In the case of implicit consent (for booking transactions only), Booxi recommends setting a data retention period to automatically anonymize PII once the applicable appointment has passed. You may also identify customers with limited consents and anonymize them based on your own specific criteria.

Booxi Anonymization Process

Booxi can configure a retention period (N days) for customer PII. When a customer has no future bookings and their most recent booking event occurred N or more days in the past, all PII associated with that customer will be automatically anonymized.

Set up the Booxi/Square integration

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 integrate Booxi with a POS

How to integrate Booxi with a Clienteling App

Requirements

Use Cases

View a client's booking history

View a staff event calendar

Book a new appointment

Manage appointments

Modify appointment details

Book without retaining personal data

Sample implementation

Relevant endpoints

Creating a New Booking

Prerequisites

Required Endpoints

Optional Endpoints

Steps

Finding or Creating a New Client to Book an Appointment

Updating an Existing Booking

Prerequisite

Required Endpoints

Optional Endpoints

Steps

Retrieving an Existing Booking

Prerequisite

Required Endpoint

Optional Endpoints

Steps

Accessing a Client's Booking History

Prerequisites

Required Endpoint

Optional Endpoints

Steps

Accessing a Staff Member's Event Calendar

Prerequisites

Required Endpoint

Optional Endpoints

Steps

Sync Your CRM Customers with Booxi Clients

ModuleLink

Available Endpoints

Using the Booking Widget to Pass Your CRM Customer ID

Prerequisites

Steps

Code Example

References

Using the Webhook to Link Your CRM Customer ID to Booxi Clients

Prerequisites

Required Endpoint

Steps

Webhook content.clientLinks Example

References

Personal Data and Consents

Booxi Anonymization Process