About the Booking Policy Snapshots API

A booking policy snapshot is a saved version of a service's booking policy at the time a booking is created. This is important because a policy may change after a customer books the service, and having a snapshot preserves the original terms.

The Booking Policy Snapshots API allows you to retrieve policy snapshots.

For managing cancellation fees, you may also want to explore the Booking Fees API.

Before You Begin

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

  • Every booking with corresponding eCommerce order has exactly one policy snapshot. Bookings without a related eCommerce order don't have a policy snapshot.
  • You can't create a booking policy snapshot using this service, you can only retrieve policy snapshots. However, you could use Get Policy to retrieve a service's booking policy just before or after creating a booking.

Use Cases

Terminology

  • Booking policy: Rules set by the business owner regarding the booking and cancellation of a service. Policies may include advance booking restrictions, cancellation deadlines, associated fees, and the maximum number of participants allowed.
  • Booking policy snapshot: The version of a service's booking policy saved at the time a booking is created. Snapshots preserve the original terms, which is useful if policies change after a booking is made.

For a comprehensive glossary of Wix Bookings terms, see Terminology.

Did this help?

Booking Policy Snapshots 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.

Notify business owners of bookings under outdated policy

Your app could give business owners an overview of all bookings made under an older version of a service policy.

To display a list of bookings with outdated booking policy:

  1. Listen to Booking Policy Updated.
  2. Retrieve all services that are using the affected policy with Query Services. Make sure to pass the relevant policy ID from the previous step as filter.
  3. Use Query Extended Bookings. For appointment-based service include bookedEntity.item.slot.serviceId in the filter. For classes or courses include bookedEntity.item.schedule.serviceId in the filter. You may use a conditional or for both filter options in a single call.
  4. Retrieve the policy snapshots for the affected bookings with List Policy Snapshots By Booking Ids.
  5. Create a summary of these bookings, highlighting the policy changes for each booking.
  6. Send the summary to the business owners.
Did this help?

Booking Policy Snapshot Object


The bookingPolicySnapshot object is the version of a service's booking policy at the time a booking is created. This allows you for example to charge customers the correct cancellation fee even after a service's cancellation policy has been updated.

Properties
idstringRead-onlyformat GUID

Booking policy snapshot ID.


bookingIdstringformat GUID

ID of the booking that's associated with this policy snapshot.


policyPolicy

Snapshot of the booking policy. at the time the corresponding booking was created.


createdDatestringRead-onlyformat date-time

Date and time the booking policy snapshot was created in YYYY-MM-DDThh:mm:ssZ format.

BookingPolicySnapshot
JSON
{ "booking_policy_snapshots": [ { "id": "c82a3f42-7605-4e24-91f5-7517ae189b7d", "booking_id": "353aa3b7-00ef-42bd-86ff-720d7ef60443", "policy": { "id": "7f31c2b3-9e6e-4b5f-b589-d524f1b3c872", "revision": 5, "created_date": "2024-01-10T10:30:00Z", "updated_date": "2024-05-20T15:45:00Z", "name": "Standard Booking Policy", "custom_policy_description": { "enabled": true, "description": "This is the standard booking policy description." }, "default": true, "cancellation_policy": { "enabled": true, "limit_latest_cancellation": false, "latest_cancellation_in_minutes": 1440 }, "reschedule_policy": { "enabled": true, "limit_latest_reschedule": false, "latest_reschedule_in_minutes": 1440 }, "cancellation_fee_policy": { "enabled": true, "cancellation_windows": [ { "amount": { "value": "10", "currency": "USD", "formatted_value": null }, "start_in_minutes": 1440 } ] }, "save_credit_card_policy": { "enabled": true } }, "created_date": "2024-06-15T10:45:00Z" } ] }
Did this help?

GET

List Policy Snapshots 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 a list of booking policy snapshots by booking IDs.

Permissions
Manage Bookings Services and Settings
Manage Bookings - all permissions
Read Bookings - all read permissions
Manage Bookings
Read Bookings - Public Data
Read Bookings - Including Participants
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/_api/booking-policy-snapshots/v1/policy-snapshots

Query Params
bookingIdsArray <string>Required

List of booking IDs to retrieve policy snapshots for.

Response Object
bookingPolicySnapshotsArray <BookingPolicySnapshot>

Retrieved booking Policy snapshots.

List policy snapshots by booking IDs
Request
cURL
curl -X GET \ 'https://www.wixapis.com/_api/booking-policy-snapshots/v1/policy-snapshots?bookingIds=353aa3b7-00ef-42bd-86ff-720d7ef60443' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "booking_policy_snapshots": [ { "id": "c82a3f42-7605-4e24-91f5-7517ae189b7d", "booking_id": "353aa3b7-00ef-42bd-86ff-720d7ef60443", "policy": { "id": "7f31c2b3-9e6e-4b5f-b589-d524f1b3c872", "revision": 5, "created_date": "2024-01-10T10:30:00Z", "updated_date": "2024-05-20T15:45:00Z", "name": "Standard Booking Policy", "custom_policy_description": { "enabled": true, "description": "This is the standard booking policy description." }, "default": true, "cancellation_policy": { "enabled": true, "limit_latest_cancellation": false, "latest_cancellation_in_minutes": 1440 }, "reschedule_policy": { "enabled": true, "limit_latest_reschedule": false, "latest_reschedule_in_minutes": 1440 }, "cancellation_fee_policy": { "enabled": true, "cancellation_windows": [ { "amount": { "value": "10", "currency": "USD", "formatted_value": null }, "start_in_minutes": 1440 } ] }, "save_credit_card_policy": { "enabled": true } }, "created_date": "2024-06-15T10:45:00Z" } ] }
Errors
404Not Found

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?