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:
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.
It's important to note the following points before starting to code:
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.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.
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:
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.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:
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.PREVIEW
since the customer hasn't
canceled the associated booking.priceOverride
object with the amount stored on your servers.Your app could display information about the fee customers would have to be before they cancel their booking.
To display cancellation fee details:
withBookingPolicySettings
to true
and provide a time range as query.filter
.
This retrieves all bookings in the given range including their booking policies.allowedActions. cancel
field is set to true
.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.Booking fee ID.
ID of the booking associated with the fee.
Cancellation fee details.
Information about the booking policy snapshot according to which the fee was created.
{
"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
}
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.
IDs of the bookings to retrieve booking fees for.
IDs of the multi service bookings to retrieve booking fees for.
List of retrieved booking fees.
Paging metadata.
curl -X GET \
'https://www.wixapis.com/_api/booking-fees/v1/booking-fees?bookingIds=b5d05e4b-4e75-4fa8-a8de-1827682ff03c' \
-H 'Authorization: <AUTH>'
{
"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"
}
}
]
}
There is 1 error with this status code:
See the entire list and learn more about Wix errors.
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.
IDs of the bookings for which to apply booking fees to an eCommerce order.
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.
Information about the message to the business and whether to send it if the booking fee application to the eCommerce order fails.
Booking fees that were applied as a single additional fee to the eCommerce order.
Information about the eCommerce order to which the booking fees are applied.
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"
]
}'
{
"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"
}
}
}
There is 1 error with this status code:
There are 2 errors with this status code:
There is 1 error with this status code:
There are 9 errors with this status code:
There are 2 errors with this status code:
See the entire list and learn more about Wix errors.
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:
status
isn't APPROVED
.balanceSummary.balance.amount
is lower than the
additionalFees.price.amount
to collect.additionalFeeId
doesn't belong to a Wix Bookings cancellation fee.ID of the eCommmerce order that includes the booking fees as a single
additionalFee
.
ID of the additional fee that's related to all given booking fees.
Information about whether to notify the business about failing to collect the booking fees from the customer and the message to send.
Collected amount.
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"
}'
{}
There is 1 error with this status code:
There are 2 errors with this status code:
There is 1 error with this status code:
See the entire list and learn more about Wix errors.