Skip to main content

How to integrate Booxi with a POS

Updated today

Overview

This article explains how to integrate a Point of Sale (POS) system with Booxi. It includes the following :

  • Description of use cases

  • Guidance on which approach to take depending on business needs

  • Description of relevant endpoints for each use case

Terminology

  • Client: Booxi customer / Customer: POS customer

  • Booxi Back Office: Booxi's administrative interface (referred to as BO)

Requirements

  • Booxi account

  • [If you intend to use Booxi's API] Partner API key. To obtain one, contact your Booxi representative.

  • [If your approach requires the use of webhooks] Webhook configured by Booxi. To enable this, contact your Booxi representative. Required for:

    • Client synchronization

    • Sale creation upon trigger

  • Decide whether you will use the Booxi API exclusively or in combination with a CRM connector.

  • Decide which integration approach you will take: see here for options.

Security considerations

  • Use of the Booxi API requires a Partner API key, which acts as a server-side client secret.

  • Booxi webhooks support security headers and signatures.

Use Cases

*Note: client synchronization can be done by another connector or by other means than creating a new client when it is time to create a sale

1- CRM Synchronization (required if you don't have a CRM connector or an alternative way to synchronize with Booxi)

This includes the following:

  • Create, update or delete a client in POS, and it automatically reflect in Booxi

    • *Note: Booxi clients can only be deleted if they have no future valid bookings.

  • Create, update or delete a client in Booxi, and it automatically reflect in POS.

  • When creating an appointment, find all POS customers already created.

  • When creating a sale in POS, find all Booxi clients already created.

2- Create a sale from a booking

  • In Booxi, create a sale from an appointment.

  • In POS, find a pending sale that was created from a booking and complete it.

3- Track booking payments

  • In Booxi, confirm that each appointment has been completed and paid via a POS sale.

External Reference

In order to simplify the identification of synced objects on both sides (POS and Booxi), Booxi allows you to store an external ID and additional metadata in the following objects:

  • Client / Customers

  • Service / Product

  • Staff / User / Employee

  • Merchant / Store

Each object can accept external references (1 per module) for different external solutions, identified by a module ID. This allows you to store external IDs for a POS, and for a CRM using a different module ID for the same Booxi client, store, service or staff.

Endpoints are available to find an object using an external ID, as well as retrieve and update it. Webhook events include the external references (links).

Endpoint

Description

GET /client

Find a client using an external customer ID with a specific module ID.

GET /client/{clientId}/moduleLink/{moduleId}

PUT /client/{clientId}/moduleLink/{moduleId}

Read and update the external ID along with metadata for client or customer.

GET /service/list

Find a service using an external service (or product) ID with a specific module ID.

GET /service/{serviceId}/moduleLink/{moduleId}

PUT /service/{serviceId}/moduleLink/{moduleId}

Read and update the external ID along with metadata for service.

GET /staff/list

Find a staff using an external staff (or user, employee, vendor) ID with a specific module ID.

GET /staff/{staffId}/moduleLink/{moduleId}

PUT /staff/{staffId}/moduleLink/{moduleId}

Read and update the external ID along with metadata for staff.

GET /merchant/search

Find a store using an external store ID with a specific module ID.

GET /merchant/{merchantId}/moduleLink/ {moduleId}

PUT /merchant/{merchantId}/moduleLink/ {moduleId}

Find a merchant (store) using an external store ID with a specific module ID.

CRM Sync

This section explains how you can sync the Booxi client list with the POS customer list.

Using Webhook events

By listening to the booking creation event, you can track existing and newly created Booxi clients that may not exist in the POS or be linked to a customer in the POS.

Notes:

  • Booxi has 3 types of bookings: appointments, group events (*note: group events contain reservations which can each include multiple attendees/clients) and queue.

  • New Booxi clients can be added via the creation of a client profile in the Booxi Back Office 'Clients' tab, via the manual creation of a booking in the 'Calendar' tab, via a client booking online (using the Booxi Widget) or via API (see booking and client endpoints).

    • New clients created via manual creation in the 'Clients' tab do not generate a webhook event.

    • New clients created via a booking will be included in the booking creation webhook event along with the POS customer ID if it is already matched.

Steps:

  1. Listen to appointment.created, reservation.created and queue_appointment.created events (depending on the booking types you have).

    1. event.type

  2. Identify whether the associated client is already linked to a POS customer.

    1. event.content.clientLinks (each client's POS module link)

If it is, you may update your POS customer with the provided information.

  • event.content.booking.clientCount (used for group events, as there may be multiple clients in the same booking)

  • event.content.booking.client (i.e. the client that booked)

  • event.content.booking.attendees (i.e. the attendees of a group event)

  • event.content.clients (each client's details)

If it isn't, you may search in your POS to find a match based on your matching criteria.

  • Booxi matches clients based on a combination of name and email or phone. You may decide that the email is a unique identifier.

  • Update the client link using the PUT client/moduleLink endpoint.

Whenever a customer is updated in the POS, you may use the Booxi API to sync the change so that it is reflected in Booxi.

  1. Attempt to find a matching existing client in Booxi using the GET /client endpoint.

    1. From your POS customer ID and module name (‘YOUR_POS’)

    2. From client name, email or phone

  2. If found, update the Booxi client using the PUT /client endpoint or update its link if it was not already linked using the PUT /client/moduleLink endpoint.

  3. If not found, create the client in Booxi, using the POST /client endpoint.

  4. If a client is deleted in the POS, and you want to delete their profile in Booxi, use the DELETE /client endpoint.

    1. Note that a client profile can only be deleted in Booxi if it has no future valid bookings. If this is the case, cancel or reassign the bookings to a different staff member.

    2. To find bookings associated with a client, use the GET /booking endpoint, entering a future date range and the client's Booxi ID.

Create a sale from a booking

This section explains how you can create a pending sale from a Booxi booking.

There are 3 approaches you can take:

  1. Create sale upon trigger

  2. Pre-create pending sales automatically, ahead of time

  3. Create sale upon manual selection

Notes:

  • Option 1 and 2 operate in the background, whereas option 3 requires you to support it through your POS UI.

  • It is assumed that when creating a pending sale in the POS, you will create a customer in the POS if they do not already exist, and link that customer with the Booxi client profile as described in the "CRM Sync" section of this article.

When considering which approach to take, consider the volume of appointments you have per day (i.e. the amount of pre-created sales that will be present in your POS):

  • If you have a relatively low volume of daily appointments, option 2 is recommended.

  • If you have a relatively high volume of daily appointments, option 1 is recommended.

Create sale upon trigger

Create sales for appointments based on a status change (i.e. marking a client as 'arrived' or completing an appointment), to avoid having too many sales created ahead of time.

*Note: the above is for appointments. For group reservations, Booxi only supports webhook event reservation.updated to be notified when a participant arrives (so that you can create a pending sale in advance).

Using the webhook, you can be notified when a client has arrived for their appointment and create the sale at that moment so it is ready to be closed once the appointment is completed.

Notes:

  • You may create the pending sale when the client has arrived or the appointment is completed.

  • If you choose to create the pending sale when the appointment is completed, make sure the auto-complete setting in Booxi is disabled ("My Business" tab > Complete appointment).

Steps to pre-create pending sales based on a status change:

  1. Listen to the webhook to create sales based on booking changes.

  2. Listen to appointment.status_updated, and reservation.status_updated events

    1. If the booking event is scheduled for the current day and the status has changed (i.e. booking.client.presence has changed to 'Arrived' or booking.isCompleted has changed to 'true'), create a sale for that booking.

      1. event.content.booking.totalClientTimespan.start

      2. To see the booking's state prior to the change (i.e. to compare), see event.content.previousBooking

Pre-create pending sales automatically, ahead of time

Using the API, you can find existing bookings and create pending sales. Using webhook events, you can track booking changes that happen during the day. Then, you can create or cancel pending sales using the API.

Notes:

  • Booxi bookings are usually created in advance (i.e. bookings are scheduled for a future date). However, from the POS standpoint, it may not be convenient to create pending sales too far in advance. To avoid receiving too high a volume of future pending sales, Booxi recommends listening to the relevant webhook events to cancel these sales in case the corresponding booking is canceled.

At the beginning of each day (0h00), you can fetch the current bookings to create pending sales for all the bookings scheduled for the current day.

Steps to pre-create pending sales for the day:

  1. Get the list of staff for your store (merchant ID)

    1. Use the GET /merchant/list endpoint to find your store merchant ID, or use GET /merchant/search if you've already associated an external ID to your stores using the module link.

    2. Use the GET staff/list endpoint with personnelType = Standard to get the list of staff calendars for your store.

  2. Get the current day's bookings for each staff calendar (e.g. for eventType "Appointment")

    1. Use the GET /calendar endpoint with the staff ID.

  3. Create a pending sale for each appointment

    1. It is recommended that you store the booking ID with each sale line; if not possible, at least for each sale.

Steps to create and update pending sales during the day (to catch last minute bookings or changes):

  1. Listen to the webhook to create or update sales based on booking changes.

  2. Listen to appointment.created, and reservation.created events

    1. If the booking event is scheduled for the current day, create a new sale for that booking.

      1. Check event.content.booking.totalClientTimespan.start to validate that the booking is of the current day.

  3. Listen to appointment.updated, and reservation.updated events when status is approved or requested (i.e. not canceled).

    1. If the booking event was scheduled for the current day (previousBooking) but was rescheduled to another day (booking), find the associated pending sale using the booking ID and cancel that sale.

      1. event.content.previousBooking.totalClientTimespan.start

      2. event.content.booking.totalClientTimespan.start

  4. Listen to appointment.updated, and reservation.updated events when status is canceled.

    1. If the booking event was scheduled for the current day, find the associated pending sale using the booking ID and cancel that sale.

Create sale upon manual selection

Using the API, you can find existing bookings and display them in your POS for the user to create a sale.

Notes:

  • Using this approach will require changes in your POS UI.

  • Booxi does not support UI add-ons that would trigger webhook events or call POS URLs; this means the request or action must be on the POS side.

Steps to pre-create pending sales for the day:

  1. In your POS, set up a trigger for the creation of a sale from a booking.

  2. Get the list of staff for your store (merchant ID)

    1. Use the GET merchant/list endpoint to find your store merchant ID.

    2. Use the GET staff/list endpoint with personnelType = Standard to get the list of staff calendars for your store.

  3. Get today’s bookings for each staff calendar (e.g. for eventType "Appointment")

    1. Use the GET /calendar endpoint with the staff ID.

  4. Create a pending sale for the selected booking

    1. It is recommended that you store the booking ID with each sale line; if not possible, at least for each sale.

Track booking payments

This section explains how to track POS sales in the Booxi Back-Office.

Steps:

  1. When a sale containing a booking is closed:

    1. Use the booking ID to retrieve the booking information using the GET /booking/{bookingId} endpoint.

    2. Use the PUT /booking/{bookingId}/payment/{paymentId} endpoint to add a payment to the booking, along with the referenceNumber and a sale URL.

  2. When a sale containing a booking is refunded:

    1. Use the booking ID to retrieve the booking information using the GET /booking/{bookingId} endpoint.

    2. Use the PUT /booking/{bookingId}/payment/{paymentId} endpoint to add a refund to the booking, along with the referenceNumber and a sale url.

Relevant endpoints

Here are all the endpoints relevant for completing a clienteling app integration.

Endpoint

Description

GET /booking/{bookingId}

Retrieve a specific booking.

GET /booking

Find bookings for a given client ID and date range. For example to retrieve the booking history of a client.

GET /calendar

Retrieve events (bookings and timeslots) from a specific staff calendar.

GET /merchant/list

Retrieve the list of all stores in a group (merchant group / country)

GET /staff/list

Retrieve the staff list for a given store, and find a staff from its moduleLink external ID.

GET /service

Retrieve the service list for a given store. Online services only, and can be filtered for services associated with a given staff ID.

GET /service/list

Retrieve the service list for a given store, regardless of the 'Available online' status, and find a service from its moduleLink external ID.

GET /client

Find a client with matching criteria, including a moduleLink external ID.

POST /client

Create a new client

PUT /client/{clientId}

Update an existing client

DELETE /client/{clientId}

Delete an existing client

See here for the full list of endpoints.

Related Articles
Booxi/Lightspeed integration guide
How to retrieve client records using the Booxi API
How to retrieve a client’s metadata using the Booxi API
How to Integrate Booxi with a Chatbot for Online Booking
Booxi Shopify POS app guide
Did this answer your question?