Booking Fees API: Sample Use Cases and Flows

This article shares some possible use cases your code 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 code's implementation.

Collect a cancellation fee

You 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 onBookingCanceled() 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 listBookingFeesByBookingIds().
4. Apply the booking fees to an eCommerce order, using applyBookingFeesToOrder().
5. Charge the customer with collectAppliedBookingFees().

Create a cancellation fee dashboard

You could create a dashboard that allows you to manage cancellation fees for bookings.

To create a cancellation fee dashboard:

1. Use queryExtendedBookings() 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 listBookingFeesByBookingIds() 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 applyBookingFeesToOrder() 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.