About the Booking Fees API

The Booking Fees API enables you to calculate and manage fees (currently only cancellation fees) for bookings, ensuring transparent and consistent pricing for customers.

With the Booking Fees API, your app can:

  • Preview how much customers would have to pay if they canceled their booking now.
  • Apply cancellation fees, including no show fees, to eCommerce orders.
  • Collect booking fees from the customer.

Learn more about booking policies that determine when and with which consequences customers can cancel their bookings. You can use the eCommerce Orders API to manage customer payment processes within the Wix ecosystem.

Before you begin

It's important to note the following points before starting to code:

  • Cancellation fees are the only booking fees that are supported.
  • The Booking Fees API calculates booking fees based on the booking's policy snapshot rather than the service's current booking policy.
  • Wix Bookings automatically applies the cancellation fee to the eCommerce order if the customer cancels the booking themselves. Cancellation fees aren't automatically applied to an eCommerce order if the business owner cancels the booking in their dashboard on behalf of the customer. You can use Apply Booking Fee to Order to manually apply booking fees to an eCommerce order.
  • After a cancellation fee is applied to an eCommerce order, the cancellation fee's price.value is updated to 0.00 and trigger is set to UNKNOWN_TRIGGER. You can retrieve details about applied booking fees from the additionalFee object in the related eCommerce order.
  • Applying a booking fee to an eCommerce order doesn't automatically charge the customer. Use Collect Applied Booking Fees to charge customers.
  • Currently, there is no validation that prevents idempotent requests in Collect Applied Booking Fees. This means that your code must make sure to not charge customers multiple times for the same booking fee. You could use List Transactions For Single Order to check which charges were made previously for an eCommerce order.

Use cases

Terminology

  • Booking fee: Fee for a specific booking that's calculated according to the associated booking policy snapshot. Currently, only cancellation fees, including no-show fees, are supported.
  • Additional fee: All related booking fees are applied as a single additional fee to an eCommerce order. When applying booking fees to an order, you can offer a discount to the customer.
Did this help?

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.
Did this help?

Booking Fee Object


Properties
idstringRead-onlyformat GUID

Booking fee ID.


bookingIdstringformat GUID

ID of the booking associated with the fee.


cancellationFeeCancellationFee

Cancellation fee details.


policyDetailsPolicyDetails

Information about the booking policy snapshot according to which the fee was created.

JSON
{ "id": "b9bc707c-473d-4c39-bd26-420216cdaaea", "booking_id": "b9bc707c-473d-4c39-bd26-420216cdaaea", "cancellation_fee": { "price": null, "status": "APPLIED_TO_ORDER", "trigger": "UNKNOWN_TRIGGER" }, "policy_details": null }
Did this help?

GET

List Booking Fees By Booking Ids


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves booking fees by booking IDs and multi service booking IDs.

Instead of returning bookingFee objects with the cancellationFee.price.value set to 0.00, the endpoint doesn't return a bookingFee object for the relevant booking IDs. For example, no bookingFee object is returned if the canceled booking was free or if the booking was canceled before the start of the earliest cancellation window.

If the service's booking policy has been updated since the booking was created, booking fees are calculated according to the policy snapshot rather than the current version of the policy.

This endpoint calculates the cancellation fee amount based on the time of the call, you can't specify a time. Similarly, it calculates the cancellation fee based on the number of participants who canceled, not a provided number.

A cancellationFee.status of PREVIEW indicates that the booking fee is informational only; the customer isn't required to pay it. When the status is set to UNKNOWN_STATUS there is no eCommerce order associated with the booking. For example, if a custom checkout was used for the booking instead of the Wix eCommerce checkout.

If multiple events would trigger the calculation of a booking fee, for example when a booking is first canceled and then marked as not attended, Wix calculates the booking fee based on the first trigger. In this example, the booking cancellation.

Permissions
Manage Bookings - all permissions
Read Bookings - all read permissions
Manage Bookings
Read Bookings - Including Participants
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/_api/booking-fees/v1/booking-fees

Query Params
bookingIdsArray <string>

IDs of the bookings to retrieve booking fees for.


multiServiceBookingIdsArray <string>

IDs of the multi service bookings to retrieve booking fees for.

Response Object
bookingFeesArray <BookingFee>

List of retrieved booking fees.


pagingMetadataPagingMetadata

Paging metadata.

Request
cURL
curl -X GET \ 'https://www.wixapis.com/_api/booking-fees/v1/booking-fees?bookingIds=b5d05e4b-4e75-4fa8-a8de-1827682ff03c' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "bookingFees": [ { "id": "b5d05e4b-4e75-4fa8-a8de-1827682ff03c", "bookingId": "b5d05e4b-4e75-4fa8-a8de-1827682ff03c", "cancellationFee": { "price": { "value": "5.0", "currency": "USD" }, "status": "NOT_YET_APPLIED_TO_ORDER", "trigger": "NOT_ATTENDED" }, "policyDetails": { "id": "295e2750-852f-4c52-9693-fc6c0d0c587b", "description": "This is our policy" } } ] }
Errors
400Invalid Argument

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?

POST

Apply Booking Fees To Order


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Applies booking fees to an eCommerce order.

The booking fees are added as a single additional fee to the eCommerce order. The order's additionalFee.lineItemIds array is set to the list of corresponding booking IDs. By default, the additionalFee.price.amount is the sum of all booking fee prices. But you may provide a priceOverride instead. The override price can't be higher than the sum of all booking fees.

Apply Booking Fees to Order also updates the prices of all affected line items in the relevant eCommerce order to zero. After a cancellation fee is applied to an eCommerce order, the cancellation fee's price.value is updated to 0.00 and its trigger is set to UNKNOWN_TRIGGER. You can retrieve the fee amount from the corresponding additionalFee object of the eCommerce order with Search Orders.

If you apply multiple booking fees to an eCommerce order, they either all fail or all succeed together. For example, the call fails if the booking fees are associated with different eCommmerce orders.

Endpoint
POST
https://www.wixapis.com/_api/booking-fees/v1/booking-fees/apply

Body Params
bookingIdsArray <string>Requiredformat GUIDminItems 1maxItems 5

IDs of the bookings for which to apply booking fees to an eCommerce order.


priceOverridePriceOverride

Custome price override for the additional fee that's added to the eCommerce order. The override mustn't exceed the sum of all booking fees. You must have the OVERRIDE_BOOKING_FEE_PRICE permission to use this property.


businessNotificationBusinessNotification

Information about the message to the business and whether to send it if the booking fee application to the eCommerce order fails.

Response Object
bookingFeesArray <BookingFee>

Booking fees that were applied as a single additional fee to the eCommerce order.


ecomOrderInfoEcomOrderInfo

Information about the eCommerce order to which the booking fees are applied.

Request
cURL
curl -X POST \ 'https://www.wixapis.com/_api/booking-fees/v1/booking-fees/apply' \ -H 'Authorization: <AUTH>' \ -d '{ "bookingIds": [ "a717b687-aaa8-4e35-85ba-adbd88bbadd8", "ff04b4b3-b386-4db1-8990-60c5ec6f4229" ] }'
Response
JSON
{ "bookingFees": [ { "id": "a717b687-aaa8-4e35-85ba-adbd88bbadd8", "bookingId": "a717b687-aaa8-4e35-85ba-adbd88bbadd8", "cancellationFee": { "price": { "value": "5.0", "currency": "USD" }, "status": "APPLIED_TO_ORDER", "trigger": "NOT_ATTENDED" }, "policyDetails": { "id": "295e2750-852f-4c52-9693-fc6c0d0c587b", "description": "This is our policy" } }, { "id": "ff04b4b3-b386-4db1-8990-60c5ec6f4229", "bookingId": "ff04b4b3-b386-4db1-8990-60c5ec6f4229", "cancellationFee": { "price": { "value": "5.0", "currency": "USD" }, "status": "APPLIED_TO_ORDER", "trigger": "NOT_ATTENDED" }, "policyDetails": { "id": "295e2750-852f-4c52-9693-fc6c0d0c587b", "description": "This is our policy" } } ], "ecomOrderInfo": { "orderId": "f8131b11-4a40-461e-939e-f67961ecf593", "additionalFeePrice": { "amount": "10.0", "formattedAmount": "$10.00" } } }
Errors
403Permission Denied

There is 1 error with this status code:

404Not Found

There are 2 errors with this status code:

409Already Exists

There is 1 error with this status code:

428Failed Precondition

There are 9 errors with this status code:

500Internal

There are 2 errors with this status code:

See the entire list and learn more about Wix errors.

Did this help?

POST

Collect Applied Booking Fees


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Collects booking fees by charging the customer using the payment method that's saved on the corresponding eCommerce order.

Warning: Currently, there is no validation that prevents idempotent requests. This means that your code must make sure to not charge customers multiple times for the same booking fee. You could use List Transactions For Single Order to check which charges were made previously for an eCommerce order.

An HTTP status of 200 means that all booking fees were successfully collected. Any other HTPP status means that collection failed.

Collects the order's additionalFees.price.amount that's related to the booking fees. If there are multiple additional fees on the eCommerce order, the amount that's collected differs from priceSummary.totalAdditionalFees.amount.

Possible failure reasons include:

  • The order's status isn't APPROVED.
  • There is no payment method saved on the order.
  • The order's balanceSummary.balance.amount is lower than the additionalFees.price.amount to collect.
  • The order's additionalFeeId doesn't belong to a Wix Bookings cancellation fee.
Endpoint
POST
https://www.wixapis.com/_api/booking-fees/v1/booking-fees/collect

Body Params
orderIdstringRequiredformat GUID

ID of the eCommmerce order that includes the booking fees as a single additionalFee.


additionalFeeIdstringRequiredformat GUID

ID of the additional fee that's related to all given booking fees.


businessNotificationBusinessNotification

Information about whether to notify the business about failing to collect the booking fees from the customer and the message to send.

Response Object
collectedPriceCollectedPrice

Collected amount.

Collect booking fees
Request
cURL
curl -X POST \ 'https://www.wixapis.com/_api/booking-fees/v1/booking-fees/collect' \ -H 'Authorization: <AUTH>' -d '{ "order_id": "b12ac1a5-810b-45ed-8b23-8a24cc31bbd0", "additional_fee_id": "981a1567-c02f-4a1f-9c3e-c86ff891ecbf" }'
Response
JSON
{}
Errors
400Invalid Argument

There is 1 error with this status code:

404Not Found

There are 2 errors with this status code:

428Failed Precondition

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?