How to Implement Online Booking With a Client Account

This article will present how online booking can be implemented into an ecommerce or website customer account.

Please take note that this implementation requires partner level permission and a partner API Key. Additionally, a client module must be configured to update any client ID generated by an external source. If you haven’t been provided with a Partner API key or if a client module is not configured for your merchant, please contact your Booxi representative. 

Be reminded that the URLs at which you access the API or the Booking Widget depend on your hosting region. This article will present examples from a North American hosting. Please update the URL in accordance with your hosting region.

Implementation

The following implementation is provided as an example. Depending on your website or ecommerce platform the implementation might differ. 

The implementation process can be divided into 4 main steps as listed below.

1. Gathering a customer’s information.
2. Opening the Booking Widget.
3. Inviting new customers to sign up.
4. Pushing any new customer ID to Booxi.

---

Gather a Customer’s Information

The first step in gathering the customer’s information is to verify if there is a session. If there is no active session, customers should be redirected to a sign in page or be allowed to continue as a guest.

For returning customers or customers who have signed up to the website, gather their personal information from their customer account or profile.

For new customers or guests, their personal information will be collected by the Booking Widget during the booking process. New customers should be invited to sign up after they completed their booking by configuring a redirection link.

---

Opening the Booking Widget

Implementing the Booking Widget to a webpage is simple and forthright. For details on how to implement the widget, please consult our implementation guide.

Depending if a client’s information has been collected or not during the previous step, open the Booking Widget using one of the following scenarios.

Opening the Booking Without Customer’s Information

To open the Booking Widget without providing any client information, use the below code sample. A client’s information will be collected on the client information form.

In the example below, the Booking Widget is mapped to the “onclick” event of a button. However, it could be mapped on any HTML element.

Take this opportunity to redirect the new customers to a sign up page once a booking has been successfully completed by setting the property “onBookedRedirectTo” with your signup URL.

<button onclick="BookNow.open({
                 apiKey:'YOUR_API_KEY_HERE',
                 onBookedRedirectTo:'YOUR_SIGNUP_URL'})"> Book Now
</button>

Opening the Booking Widget With Customer’s Information

The following code sample showcases how to open the Booking Widget with a client's information in parameter using the “client” object. The content of that object should be set per the customer’s personal information gathered during the previous step. For more details about the properties of the “client” object, consult the implementation guide.

<button onclick="BookNow.open({ 
                 apiKey: 'YOUR_API_KEY_HERE',
                 client: {
                    isAttending: true,
                    firstName: CLIENT_FIRST_NAME',
                    lastName: 'CLIENT_LAST_NAME',
                    email: 'CLIENT_EMAIL_ADDRESS',
                    mobilePhoneNumber: 'CLIENT_PHONE_NUMBER',
                    remindByEmail: true,
                    remindBySMS: false,
                    address: {
                       street: 'STREET',
                       city: 'CITY',
                       country: 'COUNTRY',
                       state: 'STATE',
                       postalCode:'POSTALCODE'
                    },
                    additionalRequest: 'ANY ADDITIONAL DETAILS',
                    hideAdditionalRequest: false,
                    membershipId: 'MEMBERSHIPID',
                    customerId: 'CUSTOMERID',
                    skipClientForm: false}
                 })"> Book Now
</button>

The property “skipClientForm” can be used to skip the client information form but only if all mandatory information is provided. In case any information is missing , the client information form will appear during the booking process.

---

 

Inviting New Customers to Sign Up

Once a booking has been completed successfully, new customers will be redirected to a signup URL (if the property onBookedRedirectTo is set) where they can create a new customer account or profile. After completing their registration, update the client record in Booxi with the client ID generated by your website or ecommerce platform.

---

 

Pushing any New Customer ID to Booxi

Update any new external customer ID by using the endpoint PUT /client/{clientId}/moduleLink/{moduleId}. The request must include the Booxi clientId and the moduleId the link is for. Optionally, include an external client ID to update in the Booxi client record and any other metadata.

 

Mandatory Parameters

 

Optional Parameters

 

Request URL for the North America

https://api.booxi.com/booking/v1/client/YOUR_CLIENT_ID/moduleLink/YOUR_MODULE_ID

cURL

curl -X PUT 
"https://api.booxi.com/booking/v1/client/YOUR_CLIENT_ID/moduleLink/YOUR_MODULE_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_APRTNER_API_KEY" 
-H  "Content-Type: application/json" -d "{\"externalId\":\"NEW_CLIENT_ID\",\"metadata\":{\"loyaltyTier\":\"member\"}}"

Request URL for Europe

https://api.booxi.eu/booking/v1/client/YOUR_CLIENT_ID/moduleLink/YOUR_MODULE_ID

cURL

curl -X PUT 
"https://api.booxi.eu/booking/v1/client/YOUR_CLIENT_ID/moduleLink/YOUR_MODULE_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_APRTNER_API_KEY" 
-H  "Content-Type: application/json" -d "{\"externalId\":\"NEW_CLIENT_ID\",\"metadata\":{\"loyaltyTier\":\"member\"}}"

Request Body (example)

{
  "externalId": "cus1001",
  "metadata": {
    "loyaltyTier": "member"
  }
}

You can test this API at the following links.

Successful JSON Response

When the query is successful, the client link will be updated with the new external ID and metadata provided (if any).

Here’s an example of a successful response:

{
  "link": {
    "moduleId": "YOUR_MODULE_ID",
    "clientId": BOOXI_CLIENT_ID,
    "externalId": "YOUR_CLIENT_ID",
    "metadata": {
      "loyaltyTier": "member"
    },
    "createdOn": "2023-11-01T07:15:00Z",
    "modifiedOn": "2023-11-01T09:03:17Z"
  },
  "client": {
    "id": BOOXI_CLIENT_ID,
    "merchantId": YOUR_MERCHANT_ID,
    "firstName": "CLIENT_FIRST_NAME",
    "lastName": "CLIENT_LAST_NAME",
    "email": "CLIENT_EMAIL",
    "homePhoneNumber": "CLIENT_HOME_PHONE",
    "mobilePhoneNumber": "CLIENT_MOBILE_PHONE",
    "metadata": {
      "classification": "supplemental"
    }
  }
}

Limitations

• If provided, metadata will replace any existing information found in a client record. To avoid losing any important data, it is recommended to make a copy of the client link before updating its content.

References

For more information about the Booxi APIs and their usage, please 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 / 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.