Use Cases
      Back to home
      1. Knowledge Base
      2. Webhooks & APIs
      3. Use Cases

      How to Build an Event Page with Custom Booking Using the API

      This article showcases how to use the API to create a custom booking experience following simple steps.

      The Booxi API can easily be used to create a landing page to promote a single event and capture online booking through a custom experience. This article showcases how to use the API to create a custom booking experience with the following simple steps:

      • Obtain a Partner API Key
      • Collect client and attendees information
      • Create a booking by calling POST /booking
      • Ask for an online payment
      • Update the booking with payment status by calling PUT /booking

      Online payment being optional, feel free to skip this step if it isn’t applicable to your case. Please take note that this article doesn’t cover how to implement a payment solution to your website. Keep in mind that Booxi can be configured to automatically cancel an unpaid booking after a delay, which is why we do not cover cancel booking in this article.

      Using a Partner API key

      In order to use the /booking API, you need a Partner API key, which must be obtained from your Booxi Account Manager. Unlike the Merchant API Key, the Partner API key must only be used in server side (backend) code to ensure its secrecy. 


      You can test APIs with your Partner API key using the following Swagger page:

      For North America servers: https://api.booxi.com/doc/booking.html#/

      For Europe servers: https://api.booxi.eu/doc/booking.html#/

      Collect Information

      To create a booking, you will need to collect information to identify the client and attendees. There are 3 common practices to do so:

      1. Use the Book Now widget and avoid developing a custom booking experience. Simply assign the eventID as a parameter to “Book Now”.
      2. Use a web session to retrieve the required client information such as name, email and mobile number to prefill the “Book Now” client’s form, or use the  POST /booking API.
      3. Create a client form to capture the minimal required information to use the POST /booking API.

      If you prefer not to capture the attendees identification you can use placeholders such as Attendee 1, Attendee 2 and so on. However the client information is mandatory.

      Create a Booking

      To book an appointment or a reservation in a group session, call the POST /booking API. Please make sure the data is properly formatted as shown in the example below. Pay special attention to “bookingMethod” and “groupEventId” as they are specific to group reservation. Be reminded that the “Group Event ID” must be created in your Booxi calendar beforehand.

       

      If your service is configured to immediately send the booking confirmation (not after payment is completed), this API call will also trigger the release of the confirmation message to the client.  If you use the Booxi webhook, you can also listen to the reservation.created event which will be triggered when calling this API.

       

      Request Body

      {
         "merchantId": YOUR_MERCHANT_ID,
         "bookingMethod": "GroupReservation",
         "groupEventId": YOUR_GROUP_EVENT_ID,
         "client":
         {
            "firstName": "Mike",
            "lastName": "Abbott",
            "email": "mike.abbott@domain.com",
            "homePhoneNumber": "111-222-3333",
            "mobilePhoneNumber": "444-555-6666",
            "remindByEmail": true,
            "remindBySMS": false,
            "isAttending": true
        },
        "attendees":
        [
           {
              "firstName": "Mike",
              "lastName": "Abbott",
              "email": "mike.abbott@domain.com",
              "homePhoneNumber": "111-222-3333",
              "mobilePhoneNumber": "444-555-6666",
              "remindByEmail": true,
              "remindBySMS": false,
              "isRequester": true
           }
        ],
        "clientCommunication": "ClientAndAttendees",
        "createdBy": "Client"
      }

       

      Request URL

      https://api.booxi.com/booking/v1/booking

       

      cURL

      curl -X POST 
      "https://api.booxi.com/booking/v1/booking?rules=&language=eng"

      -H  "accept: application/json"
      -H  "Content-Type: application/json"

      -d "{\"merchantId\":1002,\"bookingMethod\":\"GroupReservation\",\"groupEventId\":213,
      \"client\":{\"firstName\":\"Emilie\",\"lastName\":\"Authier\",
      \"email\":\"emilie.authier@booxi.com\",\"homePhoneNumber\":\"\",\"mobilePhoneNumber\":\"\",
      \"remindByEmail\":true,\"remindBySMS\":false,
      \"additionalRequest\":\"Can we bring our own ingredients?\",
      \"isAttending\":true},\"attendees\":[{\"firstName\":\"Emilie\",\"lastName\":\"Authier\",
      \"email\":\"emilie.authier@booxi.com\",\"homePhoneNumber\":\"\",\"mobilePhoneNumber\":\"\",
      \"remindByEmail\":true,\"remindBySMS\":false,\"isRequester\":true}],
      \"clientCommunication\":\"ClientAndAttendees\",\"createdBy\":\"Client\"}"

       

      Pay attention to the following properties:

      Property

      Description

      Example

      client.isAttending

      Set to true if the client who makes the reservation is also attending.

      "isAttending": true

      attendee.isRequester

      Identifies (true) which attendee is the client who made the reservation.

      "isRequester": true

      clientCommunication

      Identifies who will receive notification messages for this reservation. Possible values are: “DoNotSend”, “ClientOnly” and “ClientAndAttendees”

      "clientCommunication":"DoNotSend"

      Once the booking is successful, Booxi will send a response as a JSON object. The JSON object will include important information such as the bookingId and onlinePaymentId. Both will be required to collect payment and keep the records up to date.

       

      Here is an example of a successful response:

      {
        "bookingId": "A00001234",
        "merchantId": 1002,
        "bookingMethod": "Appointment",
        "status": "Approved",
        "isCompleted": false,
        "startsOn": "2022-02-20T16:00:00Z",
        "totalClientTimespan": {
          "start": "2022-02-20T16:00:00Z",
          "end": "2022-02-20T16:30:00Z",
          "duration": 30
        },
        "staffId": 582,
        "items": [
          {
            "serviceId": 1000,
            "serviceName": "...",
            "price": {
              "visibility": "Show",
              "amount": "5.00",
              "amountPerPerson": "0.00",
              "amountPerHour": "0.00",
              "currency": "CAD",
              "isStartingAt": false,
              "tax": "None"
            },
            "reservedClientTimespan": {
              "start": "2022-02-20T16:00:00Z",
              "end": "2022-02-20T16:30:00Z",
              "duration": 23
            },
            "duration": 23,
            "spacingAfter": 0,
            "isBusySpacingAfter": true
          }
        ],
        "location": "Business",
        "locationText": "",
        "client": {
          "firstName": "Emilie",
          "lastName": "Authier",
          "email": "emilie.authier@booxi.com",
          "homePhoneNumber": "",
          "mobilePhoneNumber": "",
          "presence": "Expecting",
          "remindByEmail": false,
          "remindBySMS": false,
          "additionalRequest": ""
        },
        "payment": {
          "total": "5.00",
          "paid": "0.00",
          "onlinePaymentId": "P00001234",
          "onlinePaymentAmount": "2.00",
          "onlinePaymentStatus": "Requested"
        },
        "createdOn": "2022-01-17T20:10:38Z",
        "createdBy": "Staff",
        "modifiedOn": "2022-01-17T20:10:38Z",
        "modifiedBy": "Staff",
        "isScheduled": true,
        "clientCount": 1
      }

      If your event requires payment, now would be the time to redirect your client to a payment solution such as a shopping cart or a payment/checkout page.

      Collect Payment

      Using the information found in the JSON object sent by Booxi,  you can collect the payment associated with your event. To do so, consider one of the following options:

      1. Use the Shopping Cart Redirection
        If you are using the Book Now widget, consult this article to learn how to redirect your client to your shopping cart. 

      2. Use a Payment or Checkout Page
        If you are using a payment or checkout page, continue to the next topic to update the payment status.

      Update Booking with Payment Status

      Update the booking payment status by calling PUT /booking/{bookingId}/payment/{paymentId} using your booking and online payment id. If your service is configured to send the booking confirmation once the full payment is completed, this API call will also trigger the release of the confirmation message to the client. If you use the Booxi webhook, you can also listen to the appointment.online_payment event which will be triggered when calling this API. The updated booking data should be formatted as per the example shown below.

       

      Request Body

      {
         "status": "Collected",
         "amount": "10.00",
         "referenceNumber": "YOUR_REFERENCE_NUMBER"
      }

       

      Request URL

      https://api.booxi.com/booking/v1/booking/A00001234/payment/P00001234

       

      cURL

      curl -X PUT 
      "https://api.booxi.com/booking/v1/booking/A00001234/payment/P00001234"
       
      -H  "accept: application/json" 
      -H  "Content-Type: application/json" 

      -d "{\"status\":\"Collected\",\"amount\":\"10.00\",\"referenceNumber\":\"\"}"

       

      Once the payment has been recorded successfully, Booxi will, once again, send a response.

      {
         "payment":
         {
            "id": "P00001234",
            "bookingId": "A00001234",
            "merchantId": 1,
            "paymentMethod": "ShoppingCart",
            "status": "Requested",
            "amount": "10.99",
            "referenceNumber": "cart_1G4DO62eZvKYlo2Cig7bioUp",
            "createdOn": "2021-01-17T07:15:00Z",
            "collectedOn": "2021-01-17T07:15:01Z"
         }
      }

       

      With that information you can now update your own records and complete the process. Integrating a booking solution to a custom event page is that simple. 

      References

      For more information about the API and its usage, refer to the following links:

      Where can API keys be found:

      • 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.