How to Update an Appointment Using the API

Learn about the PUT/booking endpoint.

Using the PUT /booking endpoint, the Booxi API now provides a way to update an appointment as a member of staff. This new functionality can only be employed for appointment type bookings.

Please take note that this endpoint requires a partner API Key. If you haven’t been provided with such a key, please contact your Booxi representative.

Be reminded that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting.

Important Note
Booxi keeps track of who last changed a booking. Even though the parameters modifiedBy and modifiedByStaffId are optional and assigned default values when omitted from the request body, it is recommended to explicitly include “modifiedBy”:”Staff” and “modifiedByStaffId”:YOUR_STAFF_ID in all requests. The staffId provided must be valid and belong to your merchant. If not, the request will fail. If the staffId is missing, the account owner will be recorded as the staff who made the changes.

---

 

Overview of the possible appointment statuses

Here is an overview of the possible appointment status, the corresponding API object properties, and the status as appearing in the Back Office.

*This property is not required when making calls to the API.

---

 

PUT /booking Capabilities Overview

The PUT /booking endpoint allows you to change the status of an appointment but also to reschedule it.

The section below will first address how to change the status of a appointment and then, how to reschedule it.

Updating the Status of an Appointment

To update the status of an appointment, use the PUT /booking/{bookingId} endpoint. Your request must minimally include a valid booking ID. 

Mandatory Parameters

 

Request URL for North America

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

cURL

curl -X POST 
"https://api.booxi.com/booking/v1/booking/YOUR_BOOKING_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
-H  "Content-Type: application/json" 
-d "{\"status\":\"STATUS\",\"client\":{\"presence\":\"PRESENCE\"},\"isCompleted\":BOOLEAN}"

 

Request URL for Europe

https://api.booxi.eu/booking/v1/booking/YOUR_BOOKING_ID

cURL

curl -X POST 
"https://api.booxi.eu/booking/v1/booking/YOUR_BOOKING_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
-H  "Content-Type: application/json" 
-d "{\"status\":\"STATUS\",\"client\":{\"presence\":\"PRESENCE\"},\"isCompleted\":BOOLEAN}"

 

Optional Parameters

 

Example with all parameters:

Request URL for North America

https://api.booxi.com/booking/v1/booking/YOUR_BOOKING_ID?language=eng

cURL

curl -X POST 
"https://api.booxi.com/booking/v1/booking/YOUR_BOOKING_ID?language:eng" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
-H  "Content-Type: application/json" 
-d "{\"status\":\"STATUS\",\"client\":{\"presence\":\"PRESENCE\"},\"isCompleted\":BOOLEAN,
   \"modifiedBy\":\"Staff\", \"modifiedByStaffId\":YOUR_STAFF_ID}"

 

Depending on how you wish to update the appointment , the content of the request body will vary. 

---

 

Supported Appointment Status Transitions

The table below presents the status transitions that are allowed.

Approve an Appointment

To approve an appointment, you must call the API passing:

• set status to “Approved”.
• set the client’s presence to “Expecting”.
• set isCompleted to false.

Note: The Back Office will display the appointment as status “Approved”.

Request Body

{
  "status": "Approved",
  "client": {
    "presence": "Expecting"
  },
  "isCompleted": false
  "modifiedBy": "Staff",
  "modifiedByStaffId": YOUR_STAFF_ID
}

 

Conditions for a Successful Response

The appointment must be scheduled (date and time) and have a staff assigned.

 

Conditions that result in error code 409

• The appointment is not scheduled.

  {
    "message": "The booking has no time scheduled in any calendar and the requested
                modification required a scheduled booking.",
    "code": 409,
    "error": "BookingNotScheduled"
  }

---

Cancel an Appointment

To cancel an appointment, you must call the API passing:

• set status to “Cancelled”
• set the client’s presence to “Expecting”
• set isCompleted to false.

Note: The Back Office will display the appointment as status “Cancelled”.

Request Body

{
  "status": "Cancelled",
  "client": {
    "presence": "Expecting"
  },
  "isCompleted": false
  "modifiedBy": "Staff",
  "modifiedByStaffId": YOUR_STAFF_ID
}

 

Conditions for a Successful Response

A booking can be cancelled regardless of its previous state except if it’s been cancelled by the client prior to the request.

 

Conditions that result in error code 409

• The appointment has been canceled by the client.

  {
    "message": "The booking is already canceled by the client and does not allow
                the requested modification.",
    "code": 409,
    "error": "BookingIsCanceledByClient"
  }

---

Complete an Appointment

To complete an appointment, you must call the API passing:

• set status to “Approved”
• set client’s presence to “Arrived”
• set isCompleted to true

Note: The Back Office will display the appointment as status “Completed”.

Request Body

{
  "status": "Approved",
  "client": {
    "presence": "Arrived"
  },
  "isCompleted": true
  "modifiedBy": "Staff",
  "modifiedByStaffId": YOUR_STAFF_ID
}

 

Conditions for a Successful Response

The booking must be scheduled (date and time) and have a staff assigned.

 

Conditions that result in error code 409

• The appointment is not scheduled.

  {
    "message": "The booking has no time scheduled in any calendar and the requested
                modification required a scheduled booking.",
    "code": 409,
    "error": "BookingNotScheduled"
  }

---

Notify that the client has arrived for his appointment

To notify that the client has arrived or that the appointment is on going, you must call the API passing:

• set status to “Approved”
• set client’s presence to “Arrived”
• set isCompleted to false

Note: The Back Office will display the appointment as status “Arrived”.

Request Body

{
  "status": "Approved",
  "client": {
    "presence": "Arrived"
  },
  "isCompleted": false
  "modifiedBy": "Staff",
  "modifiedByStaffId": YOUR_STAFF_ID
}

 

Conditions for a Successful Response

The booking must have a staff assigned, be scheduled (date and time) with its start time on the current day or in the past. Additionally, its current status must not be “Completed”.

 

Conditions that result in error code 409

• The appointment is not scheduled.

  {
    "message": "The booking has no time scheduled in any calendar and the requested
                modification required a scheduled booking.",
    "code": 409,
    "error": "BookingNotScheduled"
  }

• The appointment is scheduled in the future.

  {
    "message": "The booking is scheduled to start on a future day and the requested
                modification can only be performed starting from the day that it starts on.",
    "code": 409,
    "error": "BookingNotToday"
  }

• The appointment is completed.

  {
    "message": "The booking is completed and cannot be modified",
    "code": 409,
    "error": "BookingIsCompleted"
  }

---

Notify a Client Missed His Appointment

To notify that the client has missed the appointment, you must call the API passing:

• set status to “Approved”
• set client’s presence to “NoShow”
• set isCompleted to false

Note: The Back Office will display the appointment as status “NoShow”.

Request Body

{
  "status": "Approved",
  "client": {
    "presence": "NoShow"
  },
  "isCompleted": false
  "modifiedBy": "Staff",
  "modifiedByStaffId": YOUR_STAFF_ID
}

 

Conditions for a Successful Response

The booking must have a staff assigned, be scheduled (date and time) with its start time on the current day or in the past. Additionally, its current status must not be “Completed”. Additionally, it must not be completed.

 

Conditions that result in error code 409

• The appointment is not scheduled.

  {
    "message": "The booking has no time scheduled in any calendar and the requested
                modification required a scheduled booking.",
    "code": 409,
    "error": "BookingNotScheduled"
  }

• The appointment is scheduled in the future.

  {
    "message": "The booking is scheduled to start on a future day and the requested
                modification can only be performed starting from the day that it starts on.",
    "code": 409,
    "error": "BookingNotToday"
  }

• The appointment is completed.

  {
    "message": "The booking is completed and cannot be modified",
    "code": 409,
    "error": "BookingIsCompleted"
  }

---

Rescheduling an Appointment

An appointment can be rescheduled by using the PUT /booking/{bookingId} endpoint. Your request must include a valid booking ID and identify if you request a client confirmation or not. While rescheduling an appointment, it is permitted to update the following properties (duration, price, etc.) within the same API call. 

• startsOn : new date and time on which the appointment will be rescheduled.
• staffId : ID of the staff assigned to the appointment.
• modifiedBy : “staff” is the only supported value for this property.
• modifiedByStaffId : ID of the staff who last modified the appointment.
• additionalRequest: request submitted by the client.
• quickNote: any quick note associated with the appointment.
• Items[]: The list of services (and their properties) to be associated with the booking.

Limitations

• Rescheduling is limited to appointment type bookings. Reservations and rental bookings are yet supported.
• An appointment of status "Completed", "No Show" or "Arrived" cannot be rescheduled. 
• Appointments associated with a service requiring a resource cannot be rescheduled. This condition also applies to multi-service appointments.
• Staff assigned to a rescheduled appointment must have a calendar.
• Rescheduling an appointment while setting its state to “PendingStaffApproval” is not yet supported.

Supported Appointment Status Transitions while Rescheduling

Only the following status changes are currently allowed while rescheduling an appointment.

 

Request URL for North America

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

cURL

curl -X PUT
"https://api.booxi.com/booking/v1/booking/YOUR_BOOKING_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
-H  "Content-Type: application/json" 
-d "{\"status\":\"STATUS\",\"client\":{\"presence\":\"PRESENCE\"},\"isCompleted\":BOOLEAN}"

Request URL for Europe

https://api.booxi.eu/booking/v1/booking/YOUR_BOOKING_ID

cURL

curl -X POST 
"https://api.booxi.eu/booking/v1/booking/YOUR_BOOKING_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
-H  "Content-Type: application/json" 
-d "{\"status\":\"STATUS\",\"client\":{\"presence\":\"PRESENCE\"},\"isCompleted\":BOOLEAN}"

Parameters

Reschedule and approve an appointment, without client’s confirmation

• When calling the API, pass the following in the request body:
  • Set the booking status to “Approved”.
  • Set the client’s presence to “Expecting”.
  • Set isCompleted to false.
  • Set startsOn to a valid date/time in RFC3339 format.
  • Set staffId to a valid staff that belongs to your merchant.
  Note: The back office will display the appointment with a status “Approved”.

Request Body

{
  "status": "Approved",
  "client": {
    "presence": "Expecting",
    "additionalRequest": "request"
  },
  "isCompleted": false,
  "staffId": YOUR_STAFF_ID,
  "startsOn": RESCHEDULED_DATE,
  "modifiedBy": "Staff",
  "modifiedByStaffId": YOUR_STAFF_ID,
  "quickNote": "note"
}

---

 

Reschedule and request the client to confirm the appointment

• When calling the API, pass the following in the request body:
  • Set the booking status to “PendingClientApproval”. 
  • Set the client presence to “Expecting”.
  • Set isCompleted to false.
  • Set startsOn to a valid date/time in RFC3339 format.
  • Set staffId to a valid staff that belongs to your merchant.
  Note: The back office will display the appointment with a status “Awaiting the client’s approval”.

Request Body

{
  "status": "PendingClientApproval",
  "client": {
    "presence": "Expecting"
  },
  "isCompleted": false,
  "staffId": YOUR_STAFF_ID,
  "startsOn": RESCHEDULED_DATE,
  "modifiedBy": "Staff",
  "modifiedByStaffId": YOUR_STAFF_ID
}

---

 

Modify services and their configuration while rescheduling

• The API allows you to change services, and their properties like duration, price while rescheduling.

• When calling the API, you need to pass
  • The same parameters seen in the example above, required to reschedule.
  • An array “items” containing up to 10 services to associate with your booking.

Request Body

{
  "status": "Approved",
  "isCompleted": false,
  "client": {
    "presence": "Expecting"
  },
  "staffId": YOUR_STAFF_ID,
  "startsOn": RESCHEDULED_DATE,
  "modifiedBy": "Staff",
  "modifiedByStaffId": YOUR_STAFF_ID,
  "items": [ 
    {
      "serviceId": YOUR_SERVICE_ID,
      "price": {  
        "visibility": "Show",
        "amount": "50.00",
        "amountPerPerson": "0.00",
        "amountPerHour": "0.00",
        "isStartingAt": false,
        "tax": "None"
      },
      "duration": 22,
      "spacingAfter": 0,
      "isBusySpacingAfter": true
    },
    {
      "serviceId": YOUR_SERVICE_ID,
      "price": {  
        "visibility": "Show",
        "amount": "50.00",
        "amountPerPerson": "0.00",
        "amountPerHour": "0.00",
        "isStartingAt": false,
        "tax": "None"
      },
      "duration": 22,
      "spacingAfter": 0,
      "isBusySpacingAfter": true
    }
  ]
}

---

Email and Alerts Notifications

Rescheduling an appointment with the API will trigger the same client and staff notifications as it would if it was performed in the Back Office.

---

Troubleshooting

Conditions that result in error code 409

• Rescheduling an appointment that was never scheduled, all while omitting to provide a date/time and staffId. 

  {
   "message": "The booking has no time scheduled in any calendar and the requested modification required a scheduled booking.",
   "code": 409,
   "error": "BookingNotScheduled"
  }

• Rescheduling an appointment bearing the status “Completed”
  

  {
    "message": "The booking (or the parent group event) is completed and cannot be created or modified.",
    "code": 409,
    "error": "BookingIsCompleted"
  }

• Rescheduling an appointment bearing the status “NoShow”.
  

  {
    "message": "A booking rule does not allow this operation.",
    "code": 409,
    "error": "ClientPresenceNoShow"
  }

• Rescheduling an appointment bearing the status “Client Arrived”.
  

  {
    "message": "A booking rule does not allow this operation.",
    "code": 409,
    "error": "ClientPresenceArrived"
  }

---

Testing PUT /Booking

You can test this endpoint at the following links.

 

In the section “Request body”, from the dropdown menu select the status you wish to assign.

 

---

Successful JSON Response

When the query is successful, the response will include the booking ID, details about the service(s) provided, the merchant location, the client record and the payment (if applicable).

Here’s an example of a successful response:

{
  "bookingId": "BOOKING_ID",
  "merchantId": YOUR_MERCHANT_D,
  "bookingMethod": "Appointment",
  "status": "Approved",
  "isCompleted": false,
  "startsOn": "STARTING_DATE",
  "totalClientTimespan": {
    "start": "STARTING_TIME",
    "end": "ENDING_TIME",
    "duration": 30
  },
  "staffId": YOUR_STAFF_ID,
  "items": [
    {
      "serviceId": YOUR_SERVICE_ID,
      "serviceName": "SERVICE NAME",
      "price": {
        "visibility": "Show",
        "amount": "0.00",
        "amountPerPerson": "0.00",
        "amountPerHour": "0.00",
        "currency": "CURRENCY",
        "isStartingAt": false,
        "tax": "None"
      },
      "reservedClientTimespan": {
        "start": "STARTING_TIME",
        "end": "ENDING_TIME",
        "duration": 00
      },
      "duration": 00,
      "spacingAfter": 0,
      "isBusySpacingAfter": true
    }
  ],
  "location": "LOCATION",
  "locationText": "",
  "client": {
    "id": YOUR_CLIENT_NAME,
    "firstName": "CLIENT_FIRST_NAME",
    "lastName": "CLIENT_LAST_NAME",
    "email": "CLIENT_EMAIL_ADDRESS",
    "homePhoneNumber": "CLIENT_PHONE_NUMBER",
    "mobilePhoneNumber": CLIENT_MOBILE_NUMBER"",
    "presence": "Expecting",
    "remindByEmail": false,
    "remindBySMS": false,
    "additionalRequest": ""
  },
  "payment": {
    "total": "0.00",
    "paid": "0.00",
    "onlinePaymentStatus": "None"
  },
  "createdOn": "CREATION_DATE",
  "createdBy": "Staff",
  "createdByStaffId": "YOUR_STAFF_ID",
  "modifiedOn": "MODIFICATION_DATE",
  "modifiedBy": "Staff",
  "modifiedByStaffId": "YOUR_STAFF_ID",
  "isScheduled": true,
  "clientCount": 1,
  "quickNote":""
}

 

---

Limitations

• A member of staff that has been blocked will not be prevented from calling the API. It is the merchant’s responsibility to revoke a staff member from accessing it.
• Changing an appointment status  to “pendingClientApproval” or “pendingStaffApproval” is not supported at this time.
• The API will not allow creating an appointment with “Arrived” or “NoShow” as its initial status.
• The authentication method requires a secure environment.
• The endpoint must not be exposed on a webpage but rather server side.

---

References 

Americas: https://api.booxi.com/doc/booking.html

Europe: 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.