Wix Rentals: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.

Set up a rental service

Create a service that customers can book for a flexible number of hours or days. A service supports a single unit type, so create a separate service for each. The resource's working hours determine how a multi-day reservation is stored, so review resource schedules before you start.

To set up a rental service:

1. Call Create Resource Type to define the category of bookable resources, such as conference rooms. Save the resource type ID.
2. Call Create Resource for each bookable resource, such as Room A and Room B. Set the resource type ID from step 1 and configure working hours. To make a resource bookable around the clock, leave its working hours undefined. Save each resource ID.
3. Call Create Service, specifying the following parameters:
   • type: APPOINTMENT.
   • appId: ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e.
   • primaryResourceType: The resource type ID from step 1.
   • payment.rateType: FIXED, with payment.fixed.price set to the price per unit.
   • The duration range parameters for the unit type you want, as described in the following table.
4. Save the service ID from the response.
5. Optionally, call Create Booking Policy to configure cancellation and rescheduling rules.

The following table shows the duration range parameters for each unit type. All parameters are nested under schedule.availabilityConstraints.durationRange:

Unit type	Parameters	Allowed values	Example
HOUR	hourOptions.minDurationInMinutes, hourOptions.maxDurationInMinutes	30 to 1440 minutes	60 and 480 for 1 to 8 hours
DAY	dayOptions.minDurationInDays, dayOptions.maxDurationInDays	1 to 8 days	1 and 5 for 1 to 5 days

The minimum must be less than or equal to the maximum.

Set up resource attributes

Define custom properties for your rental resources and display them on the public site. For example, a vacation rentals business can add Capacity (number), Bed Type (string), and Has WiFi (boolean) attributes to each room.

To set up resource attributes:

1. Call Create Attribute Definition for each property. Specify a unique name, a valueType, type-specific configuration (stringConfig.allowedValues for strings, numberConfig.min/max for numbers), and a defaultValue. Save the returned attribute definition ID. Definitions are created once per site.
2. Call Bulk Upsert Attribute Values with the resource ID as entityId and the list of values. Each entry is matched by attributeDefinitionId, so only the listed attributes are created or updated.
3. To display attributes on the public site, call List Entity Attributes with the resource ID as entityId. Filter the results to attributes where attributeDefinition.visibility is true, because the API doesn't enforce visibility on the backend.

Find available rental services

Display only the rental services that a customer can book in a specified date range. This is useful for building a rental catalog page that shows only services with current availability.

To find available rental services:

1. Call Query Services by Filters with the Wix Rentals app ID in query.filter and an availability window in serviceFilters. Specify localStartDate, localEndDate, and timeZone. Leave exactMatch unset so a service is returned when it has at least 1 bookable slot anywhere in the window.
2. Render the returned results. Each result contains the full service entity and an available flag set to true.
3. If the response contains pagingMetadata.cursors.next, request the next page by passing it unchanged as query.cursorPaging.cursor. Repeat until next is absent.

To also show services that have no availability in the window, set serviceFilters.includeUnavailable to true. Each unavailable service is returned with available set to false, so you can display it as greyed out. Learn more about catalog-wide availability.

Filter rental services by location and resource attributes

Narrow the rental catalog to services at a specific business location whose resources match certain attributes, such as capacity or amenities.

To filter rental services by location and attributes:

1. Call Query Services by Filters with the Wix Rentals app ID in query.filter and the location, resource type, and attribute filters in serviceFilters. Specify locationIds with IDs from List Locations, resourceTypes with the resource type ID from Create Resource Type, and attributes entries for each attribute condition, using attribute definition IDs from List Attribute Definitions. Values for the same attribute are "match any". Values for different attributes are "match all".
2. Because no date range is specified, no availability check runs. All pre-filtered rental services are returned with available set to true.

You can combine these filters with a date range in serviceFilters to return only services that also have availability in a specified window. Learn more about catalog search.

Preview the price for a rental

Show the customer the estimated price for a rental before creating the booking. Because a rental's price depends on its duration, you must specify the start and end times so Wix can calculate the duration-based price.

To preview the price:

1. Call Preview Price with a bookingLineItems entry that includes the following fields:
   • serviceId: The rental service ID.
   • resourceId: The resource ID. Required for appointment-based services.
   • localStartDate: The customer's selected start date and time, for example "2024-03-25T09:00:00".
   • localEndDate: The customer's selected end date and time, for example "2024-03-25T14:00:00".
   • timeZone: The time zone, for example "America/New_York". Required when localStartDate and localEndDate are specified.
2. Read priceInfo.calculatedPrice from the response. For an hourly service, Wix calculates the price at per-minute granularity: the duration in minutes multiplied by the service's base price divided by 60. For a daily service, Wix multiplies the base price by the number of days.

If localStartDate, localEndDate, and timeZone aren't specified, Wix can't calculate duration-based pricing and falls back to participant-based pricing only, which charges a flat rate based on the number of participants instead of the rental's duration.

Book an hourly rental

Display the available time slots, let the customer select a start and end time, and create the booking. Learn more about hourly availability.

Part 1: Select a time slot

To let the customer select when the rental starts and ends:

1. Call List Availability Time Slots with the serviceId, timeZone, fromLocalDate, and toLocalDate. Display the available start times to the customer and save the one they select.
2. Call List Availability Time Slot End Options with the serviceId and the selected start time as localStartDate. The service's maximum duration caps the response, so you don't need to specify maxLocalEndDate. Display the available end times to the customer and save the one they select.

Part 2: Create the booking

To reserve the selected time range:

1. Call Create Booking, specifying the following parameters:
   • bookedEntity.slot.serviceId: The service ID.
   • bookedEntity.slot.startDate: The selected start time.
   • bookedEntity.slot.endDate: The selected end time.
   • bookedEntity.slot.timezone: The time zone the slot was displayed in.
   • bookedEntity.slot.resourceSelections: An entry with resourceTypeId set to the service's resource type ID, and selectionMethod set to ANY_RESOURCE to let Wix assign a resource, or SPECIFIC_RESOURCE when the customer chose a particular resource.
   • contactDetails: The customer's contact details.
2. Save the booking ID from the response. Wix creates the booking with status CREATED.

If the slot was taken between selection and booking, the call fails with SLOT_NOT_AVAILABLE. If the chosen duration falls outside the service's duration range, it fails with INVALID_DURATION_PROVIDED, and the response includes the allowed range so you can display a useful message. Handle both errors by returning the customer to the slot picker.

Then handle payment for the rental.

Book a daily rental with working hours

Book a multi-day rental on a resource that has working hours. Each working day is a separate bookable unit, so the reservation becomes a linked group of bookings, 1 per day. Learn more about daily availability.

To book a daily rental on a resource with working hours:

1. Call List Availability Time Slots with the serviceId, timeZone, fromLocalDate, toLocalDate, and timeSlotsPerDay set to 1. Display the available days to the customer and save the slot list.
2. After the customer selects a start date, iterate forward through the slot list to find the consecutive available days. Stop at the first gap or when you reach the service's maximum duration. Display the valid end dates to the customer.
3. Build an array of per-day bookings, 1 for each day in the selected range. Specify the following parameters in each booking:
   • bookedEntity.slot.serviceId: The service ID.
   • bookedEntity.slot.startDate: The start of the resource's working period on that day. For example, 9 AM.
   • bookedEntity.slot.endDate: The end of the resource's working period on that day. For example, 6 PM.
   • bookedEntity.slot.timezone: The time zone the slots were displayed in.
   • contactDetails: The customer's contact details.
4. Call Create Multi Service Booking, specifying the following parameters:
   • bookings: The array of per-day bookings from step 3. A group holds between 2 and 8 bookings.
   • multiServiceBookingType: SEQUENTIAL_BOOKINGS.
5. Save the multi-service booking ID from multiServiceBookingInfo.id in the response. You need it to cancel the group later.

Wix creates the group all or nothing. If any day in the range is unavailable, or the days aren't consecutive, the call fails and no bookings are created.

Then handle payment for the rental.

Book a daily rental around the clock

Book a multi-day rental on a 24/7 resource, which has no working hours. Consecutive days form 1 unbroken block, so the whole range becomes a single booking.

To book a daily rental on a 24/7 resource:

1. Call List Availability Time Slots with the serviceId, timeZone, fromLocalDate, toLocalDate, and timeSlotsPerDay set to 1. Display the available days to the customer and save the slot list.
2. After the customer selects a start date, iterate forward through the slot list to find the consecutive available days. Stop at the first gap or when you reach the service's maximum duration. Display the valid end dates to the customer.
3. Call Create Booking, specifying the following parameters:
   • bookedEntity.slot.serviceId: The service ID.
   • bookedEntity.slot.startDate: Midnight on the first day of the rental.
   • bookedEntity.slot.endDate: Midnight on the day after the last day of the rental. For a rental from Monday to Wednesday inclusive, this is midnight on Thursday.
   • bookedEntity.slot.timezone: The time zone the slots were displayed in.
   • bookedEntity.slot.resourceSelections: An entry with resourceTypeId set to the service's resource type ID, and selectionMethod set to ANY_RESOURCE.
   • contactDetails: The customer's contact details.
4. Save the booking ID from the response.

Wix derives bookedEntity.slot.allDay and sets it to true. Don't set this field yourself.

Then handle payment for the rental.

Handle payment for a rental

Charge the customer for a rental booking through Wix eCommerce. This flow is the same for hourly and daily rentals.

To charge the customer:

1. Call Create Checkout, specifying the following parameters:
   • catalogReference.appId: The Wix Bookings app ID, 13d21c63-b5ec-5912-8397-c3a5ddb27a97. Don't use the Wix Rentals app ID here.
   • catalogReference.catalogItemId: The booking ID.
2. Call Get Checkout URL and redirect the customer to the returned URL.
3. After checkout, Wix eCommerce creates an order and updates the booking status to CONFIRMED.

Cancel a single rental booking

Cancel an hourly rental, or a daily rental on a 24/7 resource. Both are stored as a single booking. Learn more about resource schedules.

To cancel a single rental booking:

1. Call Query Extended Bookings to retrieve the booking and verify that its status allows cancellation. Save the booking ID and current revision.
2. Call Cancel Booking with the booking ID and the revision from step 1.
3. For rentals paid through Wix eCommerce, issue a refund with the eCommerce Orders API. Learn more about order billing sample flows.

Cancel a multi-day rental booking group

Cancel a daily rental on a resource with working hours. Wix stores it as a linked group of bookings, so canceling the group cancels every booking in it.

Canceling a group needs the multi-service booking ID, which Wix returns when you create the group. Store it alongside the reservation in your own records, because multiServiceBookingInfo isn't exposed on the bookings you retrieve later.

To cancel a multi-day rental booking group:

1. Retrieve the multi-service booking ID you saved when you created the group.
2. Call Cancel Multi Service Booking with that ID. This cancels every linked booking in the group.
3. For rentals paid through Wix eCommerce, issue a refund with the eCommerce Orders API.

See also

• About Wix Rentals
• Wix Rentals and the Bookings APIs
• About Wix Rentals Availability
• Bookings Writer V2 API
• Time Slots V2 API
• Attributes API
• Catalog Search API