Booking Fee API: Sample Use Cases and Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Collect a cancellation fee

Your app could collect a cancellation fee from the customer when the business cancels a booking in their dashboard on behalf of the customer. Note that Wix Bookings automatically applies the cancellation fee to an eCommerce order if the customer cancels the booking themselves.

To collect a cancellation fee:

1. Listen to the Booking Canceled event and save the booking ID.
2. Confirm that the business has canceled the booking in the dashboard by checking that initiatedBy is set to a wixUserId. Don't apply cancellation fees for bookings that were canceled by customers themselves, since Wix Bookings does that automatically.
3. Calculate the resulting booking fees with List Booking Fees By Booking Ids.
4. Apply the booking fees to an eCommerce order, using Apply Booking Fees To Order.
5. Charge the customer with Collect Applied Booking Fees.

Create a cancellation fee dashboard

Your app could display a dashboard to the business owners that allows them to manage cancellation fees for their bookings.

To create a cancellation fee dashboard:

1. Use Query Extended Booking and provide a time range as query.filter. This retrieves all upcoming bookings. If you want to display only bookings for a specific list of services, also provide the relevant service IDs in the filter. Save the list of retrieved booking IDs.
2. Display each booking to the business owners including a button to manage the related cancellation fee.
3. When the business owner clicks the manage cancellation fee button, call List Booking Fees By Booking Ids to retrieve the associated fees. You could display them in a new modal.
4. Make sure to not display fees with a status of PREVIEW since the customer hasn't canceled the associated booking.
5. In the modal, you may include one button that allows the business to discount the cancellation fee and another button to apply the fee to the corresponding eCommerce order.
6. Make sure to save discounted fee prices on your servers until the business is ready to apply them.
7. Use Apply Booking Fees to Order to apply the relevant booking fees as a single additional fee to an eCommerce order. To apply a discounted fee, provide a priceOverride object with the amount stored on your servers.

Cancel a booking on behalf of the customer

Your app could display information about the fee customers would have to be before they cancel their booking.

To display cancellation fee details:

1. Use Query Extended Booking, set withBookingPolicySettings to true and provide a time range as query.filter. This retrieves all bookings in the given range including their booking policies.
2. Display each booking to the customer. Include a cancel button, if the extended booking's allowedActions. cancel field is set to true.
3. When the customer clicks the cancel button check if the relevant booking policy snapshot's cancellationFeePolicy.enabled is set to true. Then, call List Booking Fees By Booking Ids and pass the relevant bookingId. Note that the returned cancellation fee has {"status": "PREVIEW"}, which means that the customer hasn't agreed to pay it yet.
4. Display the cancellation fee to the customer. After they've agreed to pay the fee, use Cancel Booking.
5. Wix Bookings automatically applies the cancellation fee to the order, once the booking has been canceled.