Use of this API requires a partner API Key. To obtain such a key, contact your Booxi representative.
Prior to use, consult Booxi's API fair use policy.
Remember that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting only.
API documentation links:
Using the PUT /booking endpoint, you can update an appointment as a staff member. This can be only used for appointment type bookings.
We (Booxi) keep 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 store. 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.
| Object property expected in | Object property expected in | Object property expected in |
|
Appointment Status | Status | client.presence | isCompleted | Status in Back Office |
Approved | Approved | Expecting | False | Approved |
Completed | Approved | Arrived | True | Completed |
No Show | Approved | NoShow | False | NoShow |
Arrived | Approved | Arrived | False | Arrived |
Pending Client's Approval | PendingClient | Expecting | False | Awaiting Client's Approval |
Cancelled | Cancelled | Expecting* | False* | Cancelled by Merchant |
*This property is not required when making calls to the API.
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
Parameter | Format | Description |
bookingId | bookingId | ID of the booking to update. |
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
Parameter | Format | Description |
language | language=lng | The language the content should be provided in. |
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.
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
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
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 ongoing, you must call the API passing:
set status to “Approved”
set client’s presence to “Arrived”
set isCompleted to false
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
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.
Rescheduling is limited to appointment type bookings. Reservation type 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 for 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
Parameter | Format | Description |
status | status=enum
| Mandatory The status of the booking:
|
isCompleted | isCompleted=boolean | Mandatory Indicates whether this booking has been completed. |
client.presence | client.presence=enum
| Mandatory Indicated whether this client has shown up or not to his booking. |
startsOn | startsOn=date | Optional - The date and time on which the appointment is being rescheduled. It should be formatted per the RFC3399 standard. |
staffId | staffId=staffId | Optional - The staff associated with the appointment. |
modifiedBy | modifiedBy=staff | Optional - The only value supported for this property is “Staff”. |
modifiedByStaffId | modifiedByStaffId=staffId | Optional - Id of the staff who modified the appointment. The staffId provided must be valid and belong to your merchant. If not, the request will fail. If the staffId is omitted, the account owner will be recorded as the staff who made the changes. |
additionalRequest | additionalRequest=request | Optional - additional request submitted by the client associated with the appointment. |
quickNote | quickNote=quickNote | Optional - any quick note associated with the appointment. |
items[] | Items[ {BookingItem object},... | Optional - Collection of services associated with the booking. To be specified when a modification is required to the services associated with the booking. Any existing services associated with the booking will be replaced by the services defined in the array.
A service is represented as a BookingItem object - see definition below |
BookingItem object | serviceId=serviceId serviceId=12023
duration=60
spacingAfter=30
isBusySpacingAfter=true
| Represent a service associated with a booking.
Mandatory parameters
|
Price object | Visibility=showPriceToClient visibility=true
amount=15
amountPerPerson=15
amountPerHour=pricePerHour amountPerHour=20
isStartingAtboolean=true
Tax=none | The asking price for a service or a booking item. When providing a price, all of the editable properties should be set.
|
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.
The Back Office will display the appointment with 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.
The back office will display the appointment with 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
When rescheduling, the API allows you to change services and their properties such as duration and price.
When calling the API, you must 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.
For North America | For Europe |
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 store 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 staff member 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 currently supported.
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.