Get to know our frameworks

Select an app template built on your preferred framework.

Build apps on our native app editor. Use drag and drop elements, Velo code and Wix APIs to develop custom features.

Streamline your app development process with the Wix CLI. Get a familiar developer experience with minimal setup and configuration.

Take full control over your app's tech stack, deployment, and hosting.

App templates

Wix Blocks templates

Wix CLI templates

Self-hosted templates

Kickstart your app development with templates built on your preferred Wix developer tool. Browse templates for practical foundation and get to know the Wix ecosystem.

Wix App Templates for Developers

This example apps can be used as a starting point for building your own app, for concrete examples of how to use Wix framework, or for inspiration.

Choose a template.<0 />Build an app.

Browse by:

How to build it step by step:

This template is built with:

Read how this template was built, step by step.

How we built this template

Deployment instructions:

Choose a package manager and run the command in your terminal.

Copy command

Before you get started, make sure you have the following:

Prerequisite steps

Get started with Wix CLI

Begin by setting up your Next.js project with your preferred hosting platform.

Select your hosting service

Start the deployment flow and set up your template repo on Netlify. After you finish set up, come back here and add your Netlify custom domain.

Copy the code from our Git repo to deploy your app on any platform that supports Next.js.

Start the deployment flow and set up your template repo on Vercel. After you finish set up, come back here and add your Vercel generated URL.

Add the base URL and give your app a name.

App details

Go to the app dashboard and test your app to ensure a smooth integration within the Wix ecosystem. <0>Learn more about app checks and testing</0>

Define your environment

Terminal

Related templates

Note

Warning

Your app name will be used as the namespace suffix.

Name your app to generate a namespace. This lets you refer to your app in code later on.

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

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

bookingIds

Options to use when applying booking fees to an eCommerce order.

options

ApplyBookingFeesToOrderOptions

Applies booking fees to an
[eCommerce order](https://dev.wix.com/docs/sdk/backend-modules/ecom/orders/setup).


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
[getOrder()](https://dev.wix.com/docs/sdk/backend-modules/ecom/orders/get-order).

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. In case of failure,
[onFailedToApplyBookingFeeToOrder()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/on-failed-to-apply-booking-fee-to-order)
is triggered multiple times, once for each individual fee.

import { bookingFees } from '@wix/bookings';

async function applyBookingFeesToOrder(bookingIds, options) {
  const response = await bookingFees.applyBookingFeesToOrder(bookingIds, options);
};

applyBookingFeesToOrder: Wix-hosted

import { createClient } from '@wix/sdk';
import { bookingFees } from '@wix/bookings';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { bookingFees },
  // Include the auth strategy and host as relevant
});


async function applyBookingFeesToOrder(bookingIds, options) {
  const response = await myWixClient.bookingFees.applyBookingFeesToOrder(bookingIds, options);
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

applyBookingFeesToOrder: Self-hosted

applyBookingFeesToOrder

ApplyBookingFeesToOrderResponse

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

orderId

string

Options to use when collecting booking fees that have been applied to an eCommerce order.

CollectAppliedBookingFeesOptions

Collects booking fees by charging the customer using the payment method that's
saved on the corresponding [eCommerce order](https://dev.wix.com/docs/sdk/backend-modules/ecom/orders/setup).


<blockquote class="warning">

__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 [listTransactionsForSingleOrder()](https://dev.wix.com/docs/sdk/backend-modules/ecom/order-transactions/list-transactions-for-single-order) to check which charges were made previously for an eCommerce order.
</blockquote>

An HTTP status of `200` means that all booking fees were successfully collected.
Any other HTPP status means that collection failed. Then,
[onFailedToCollectAppliedBookingFees()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/on-failed-to-collect-applied-booking-fees)
is also triggered.

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 reason's 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.

import { bookingFees } from '@wix/bookings';

async function collectAppliedBookingFees(orderId, options) {
  const response = await bookingFees.collectAppliedBookingFees(orderId, options);
};

collectAppliedBookingFees: Wix-hosted

import { createClient } from '@wix/sdk';
import { bookingFees } from '@wix/bookings';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { bookingFees },
  // Include the auth strategy and host as relevant
});


async function collectAppliedBookingFees(orderId, options) {
  const response = await myWixClient.bookingFees.collectAppliedBookingFees(orderId, options);
};

collectAppliedBookingFees: Self-hosted

collectAppliedBookingFees

CollectAppliedBookingFeesResponse

Options to use when listing booking fees.

ListBookingFeesByBookingIdsOptions

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](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-policy-snapshots/introduction)
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](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/setup).

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.

import { bookingFees } from '@wix/bookings';

async function listBookingFeesByBookingIds(options) {
  const response = await bookingFees.listBookingFeesByBookingIds(options);
};

listBookingFeesByBookingIds: Wix-hosted

import { createClient } from '@wix/sdk';
import { bookingFees } from '@wix/bookings';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { bookingFees },
  // Include the auth strategy and host as relevant
});


async function listBookingFeesByBookingIds(options) {
  const response = await myWixClient.bookingFees.listBookingFeesByBookingIds(options);
};

listBookingFeesByBookingIds: Self-hosted

listBookingFeesByBookingIds

Manage Bookings - all permissions

Read Bookings - all read permissions

Manage Bookings

Read Bookings - Including Participants

ListBookingFeesByBookingIdsResponse

IDs of the bookings to retrieve booking fees for.

Retrieves non-preview booking fees by booking IDs.

Returns only booking fees with status `APPLIED_TO_ORDER` or `NOT_YET_APPLIED_TO_ORDER`.

Use [listBookingFeesByBookingIds()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/list-booking-fees-by-booking-ids) to retrieve all booking fees.

For performance reasons when retrieving only booking fees with status  `APPLIED_TO_ORDER` or `NOT_YET_APPLIED_TO_ORDER`, we recommend using this method over listBookingFeesByBookingIds().

import { bookingFees } from '@wix/bookings';

async function listNonPreviewBookingFeesByBookingIds(bookingIds) {
  const response = await bookingFees.listNonPreviewBookingFeesByBookingIds(bookingIds);
};

listNonPreviewBookingFeesByBookingIds: Wix-hosted

import { createClient } from '@wix/sdk';
import { bookingFees } from '@wix/bookings';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { bookingFees },
  // Include the auth strategy and host as relevant
});


async function listNonPreviewBookingFeesByBookingIds(bookingIds) {
  const response = await myWixClient.bookingFees.listNonPreviewBookingFeesByBookingIds(bookingIds);
};

listNonPreviewBookingFeesByBookingIds: Self-hosted

listNonPreviewBookingFeesByBookingIds

ListNonPreviewBookingFeesByBookingIdsResponse

# About the Booking Fees API

The Booking Fees API allows you to calculate and manage fees for your
bookings, ensuring transparent and consistent pricing for customers.

With the Booking Fees API, you 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](https://dev.wix.com/docs/sdk/backend-modules/bookings/policies/introduction)
that determine when and with which consequences customers can cancel their
bookings. You can use the [eCommerce Orders API](https://dev.wix.com/docs/sdk/backend-modules/ecom/orders/introduction)
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](https://dev.wix.com/docs/sdk/backend-modules/bookings/policy-snapshots/introduction)
  and not the service's current
  [booking policy](https://dev.wix.com/docs/sdk/backend-modules/bookings/policies/introduction).
- 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
  [applyBookingFeeToOrder()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/apply-booking-fees-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 [collectAppliedBookingFees()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/collect-applied-booking-fees)
  to charge customers.
- Currently, there is no validation that prevents idempotent requests in
  [collectAppliedBookingFees()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/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
  [listTransactionsForSingleOrder()](https://dev.wix.com/docs/sdk/backend-modules/ecom/order-transactions/list-transactions-for-single-order)
  to check which charges were made previously for an eCommerce order.

## Use cases

- [Collect a cancellation fee](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/sample-flows#collect-a-cancellation-fee).
- [Create a cancellation fee dashboard](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/sample-flows#create-a-cancellation-fee-dashboard).

## Terminology

- **Booking fee**: Fee for a specific booking that's calculated according to the
  associated [booking policy snapshot](https://dev.wix.com/docs/sdk/backend-modules/bookings/policy-snapshots/introduction).
  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. You can give customers a discount when
  [applying booking fees to an order](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/apply-booking-fees-to-order).

For a comprehensive glossary of Wix Bookings terms, see
[Terminology](https://dev.wix.com/docs/sdk/backend-modules/bookings/terminology).

To use the BookingFees API, install the `@wix/bookings` package using npm or Yarn:
  ```console
npm install @wix/bookings
```

or

```console
yarn add @wix/bookings
```

Then import `{ bookingFees }` from `@wix/bookings`:

```js
import { bookingFees } from '@wix/bookings'
```
  

# 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()](https://dev.wix.com/docs/sdk/backend-modules/bookings/bookings/on-booking-canceled)
   and save the booking ID.
1. 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.
1. Calculate the resulting booking fees with
   [listBookingFeesByBookingIds()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/list-booking-fees-by-booking-ids).
1. Apply the booking fees to an eCommerce order, using
   [applyBookingFeesToOrder()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/apply-booking-fees-to-order).
1. Charge the customer with
   [collectAppliedBookingFees()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/collect-applied-booking-fees).

## 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()](https://dev.wix.com/docs/sdk/backend-modules/bookings/extended-bookings/query-extended-bookings)
   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.
1. Display each booking to the business owners including a button to manage the
   related cancellation fee.
1. When the business owner clicks the manage cancellation fee button, call
   [listBookingFeesByBookingIds()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/list-booking-fees-by-booking-ids)
   to retrieve the associated fees. You could display them in a new modal.
1. Make sure to not display fees with a status of `PREVIEW` since the customer hasn't
   canceled the associated booking.
1. 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.
1. Make sure to save discounted fee prices on your servers until the business is
   ready to apply them.
1. Use [applyBookingFeesToOrder()](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-fees/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.

bookings_booking-fees

Information about the message to the business and whether to send it if the
booking fee application to the eCommerce order fails. If multiple booking fees
couldn't be applied to the same eCommerce order, multiple Failed To Apply Booking
Fee To Order events are triggered. But only one of these events includes the
`businessNotification`.

businessNotification

BusinessNotification

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.

priceOverride

Money

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

bookingFees

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

ecomOrderInfo

EcomOrderInfo

BookingFee

ID of the booking associated with the fee.

bookingId

cancellationFee

CancellationFee

Information about the [booking policy snapshot](https://dev.wix.com/docs/sdk/backend-modules/bookings/booking-policy-snapshots/introduction)
according to which the fee was created.

policyDetails

PolicyDetails

BookingFeeStatus

message

Whether to notify the business about changes made to the booking fees.
Default is false.

notifyBusiness

boolean

price

Status of the booking fee.

+ `UNKNOWN_STATUS`: There is no eCommerce order associated with the booking.
+ `PREVIEW`: The fee is informational only; the customer doesn't have to pay it. For example, it shows how much the customer would owe if they canceled the booking now.
+ `NOT_YET_APPLIED_TO_ORDER`: The booking fee hasn't been added to the eCommerce order yet.
+ `APPLIED_TO_ORDER`: The booking fee has been added to the eCommerce order. The customer may not have paid it yet.

status

Information about what triggered the creation of the booking fee.

+ `UNKNOWN_STATUS`: There is no information about what triggered the creation of the booking fee.
+ `NOT_ATTENDED`: The booking fee was created because the customer didn't show up to the booking or canceled after the expiration of the last cancellation window.
+ `BOOKING_CANCELED`: The booking fee was created because the customer canceled the booking before the expiration of the last cancellation window.

trigger

Trigger

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

additionalFeeId

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

collectedPrice

Price

CursorPagingMetadata

Number of items returned in the response.

count

number

Cursor strings that point to the next page, previous page, or both.

cursors

Cursors

Whether there are more pages to retrieve following the current page.

+ `true`: Another page of results can be retrieved.
+ `false`: This is the last page.

hasNext

Cursor string pointing to the next page in the list of results.

additionalFeePrice

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

multiServiceBookingIds

pagingMetadata

Currency code. Must be valid ISO 4217 currency code (e.g., USD).

currency

Monetary amount. Decimal string in local format (e.g., 1 000,30). Optionally, a single (-), to indicate that the amount is negative.

formattedValue

Monetary amount. Decimal string with a period as a decimal separator (e.g., 3.99). Optionally, a single (-), to indicate that the amount is negative.

Setup