> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # ValidateBeforeCancel # Package: bookings # Namespace: BookingsValidationProvider # Method link: https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-cancel.md ## Introduction Validates whether a booking can be canceled. Wix calls this method when a customer initiates a cancellation, before the booking status is updated to `CANCELED`. Use this to enforce custom cancellation rules, for example, cancellation fees, minimum notice periods, or membership benefit reversal. If your service returns an error or times out, Wix blocks the cancellation (fail-closed behavior). --- ## REST API ### Schema ``` Method: validateBeforeCancel Description: Validates whether a booking can be canceled. Wix calls this method when a customer initiates a cancellation, before the booking status is updated to `CANCELED`. Use this to enforce custom cancellation rules, for example, cancellation fees, minimum notice periods, or membership benefit reversal. If your service returns an error or times out, Wix blocks the cancellation (fail-closed behavior). URL: null Method: POST Method parameters: param name: items | type: array | description: Items to validate. - name: booking | type: Booking | description: Booking to validate. - ONE-OF: - name: totalParticipants | type: integer | description: Total number of participants. When creating a booking, use this field only if the relevant service has fixed pricing and doesn't offer [variants and options](https://dev.wix.com/docs/rest/business-solutions/bookings/services/service-options-and-variants/introduction.md). - name: participantsChoices | type: ParticipantChoices | description: Information about the booked service choices and participant count for each choice. When creating a booking, use this field only if the booking includes multiple [service variants](https://dev.wix.com/docs/rest/business-solutions/bookings/services/service-options-and-variants/introduction.md). For example, use this for a spa package booking that includes different service levels: - 2 participants chose "Standard Package". - 1 participant chose "VIP Package". - name: serviceChoices | type: array | description: Information about the booked service choices. Includes the number of participants. - name: numberOfParticipants | type: integer | description: Number of participants for this [variant](https://dev.wix.com/docs/rest/business-solutions/bookings/services/service-options-and-variants/introduction.md). - name: choices | type: array | description: Service choices for these participants. - ONE-OF: - name: custom | type: string | description: Value for one of the choices in the [`CustomServiceOption.choices`](https://example.com) list. Choices are specific values for an option the customer can choose to book. For example, the option `ageGroup` may have these choices: `child`, `student`, `adult`, and `senior`. Each choice may have a different price. - name: duration | type: Duration | description: - name: minutes | type: integer | description: Duration of the service in minutes. Min: 1 minute, Max: 30 days, 23 hours, and 59 minutes - name: name | type: string | description: Name of the duration option. Defaults to the formatted duration e.g. "1 hour, 30 minutes". - name: optionId | type: string | description: GUID of the corresponding option for the choice. For example, the choice `child` could correspond to the option `ageGroup`. In this case, `optionId` is the GUID for the `ageGroup` option. - name: bookedEntity | type: BookedEntity | description: An object describing the bookable entity - either a specific time slot or a recurring schedule. The structure depends on the type of service being booked: __For appointment services__: Use `slot` to book a specific time slot with a service provider. Appointments are typically one-time sessions at a specific date and time. __For class services__: Use `slot` to book a specific class session. Classes are individual sessions that can have multiple participants. __For course services__: Use `schedule` to book an entire course consisting of multiple sessions over time. Courses are recurring, multi-session offerings. Choose the appropriate field based on your service type and booking requirements. - ONE-OF: - name: slot | type: BookedSlot | description: [Booked slot](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings-and-time-slots/time-slots/availability-calendar/query-availability.md). Specify `slot` when creating bookings for: - __Appointment-based services__: Individual sessions with service providers (consultations, treatments). Wix Bookings creates a new session when the booking is confirmed. - __Class services__: Group sessions at specific times (fitness classes, workshops). Wix Bookings links the booking to an existing scheduled session. For course services, specify `schedule` instead of `slot`. - name: serviceId | type: string | description: Service GUID. - name: scheduleId | type: string | description: Schedule GUID. - name: eventId | type: string | description: GUID of the corresponding [event](https://dev.wix.com/docs/rest/business-management/calendar/events-v3/introduction.md). Available for both appointment and class bookings, not available for course bookings. For appointment-based services, Wix Bookings automatically populates `eventId` when the booking `status` changes to `CONFIRMED`. For class bookings, Wix Bookings automatically populates `eventId` upon booking creation. - name: startDate | type: string | description: The start time of this slot in `YYYY-MM-DDThh:mm:ss`, `YYYY-MM-DDThh:mm:ss:SSS`, or `YYYY-MM-DDThh:mm:ss:SSSZZ` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`, `2026-01-30T13:30:00:000`, or `2026-01-30T13:30:00:000-05:00`. - name: endDate | type: string | description: The end time of this slot in `YYYY-MM-DDThh:mm:ss`, `YYYY-MM-DDThh:mm:ss:SSS`, or `YYYY-MM-DDThh:mm:ss:SSSZZ` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`, `2026-01-30T13:30:00:000`, or `2026-01-30T13:30:00:000-05:00`. - name: timezone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database). For example, `America/New_York` or `UTC`. This is the time zone in which the slot was shown to the customer at the time of booking. Wix Bookings ensures that the slot is always displayed in this same time zone to the customer, including when they view or edit their booking in the future. - name: resource | type: BookedResource | description: [Primary resource](https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resources-v2/introduction.md) for the booking. For example, the [staff member](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction.md) providing the service. - name: id | type: string | description: GUID of the booking's primary resource. - name: name | type: string | description: Resource's name at the time of booking. - name: email | type: string | description: Resource's email at the time of booking. - name: scheduleId | type: string | description: GUID of the schedule belonging to the booking's primary resource. - name: location | type: Location | description: Location where the session takes place. - name: id | type: string | description: Business location GUID. Available only for locations that are business locations, meaning the `location_type` is `"OWNER_BUSINESS"`. - name: name | type: string | description: Location name. - name: formattedAddress | type: string | description: The full address of this location. - name: formattedAddressTranslated | type: string | description: The full translated address of this location. - name: locationType | type: LocationType | description: Location type. - enum: - UNDEFINED: Undefined location type. - OWNER_BUSINESS: The business address, as set in the site’s general settings. - OWNER_CUSTOM: The address as set when creating the service. - CUSTOM: The address as set for the individual session. - name: resourceSelections | type: array | description: Information about how the customer has selected resources for the booking. Each resource type may have a different selection method. Check `resource` for resource details. - name: resourceTypeId | type: string | description: GUID of the [resource type](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/introduction.md). - name: selectionMethod | type: SelectionMethod | description: Information about how the customer has selected the resource for this resource type. - enum: - SPECIFIC_RESOURCE: The customer explicitly chose a particular resource. - ANY_RESOURCE: The customer explicitly chose "any available resource" for this resource type. - NO_SELECTION: The customer wasn't offered a resource selection or agreement option for this resource type. - name: schedule | type: BookedSchedule | description: [Booked schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/introduction.md). Specify `schedule` when creating bookings for: - __Course services__: Multi-session offerings spanning weeks or months (educational courses, training programs). Wix Bookings enrolls participants in all sessions defined by the course schedule. - name: scheduleId | type: string | description: [Schedule GUID](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/introduction.md). - name: serviceId | type: string | description: Booked service GUID. - name: timezone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database). For example, `America/New_York` or `UTC`. This is the time zone in which the schedule was shown to the customer at the time of booking. Wix Bookings ensures that the schedule is always displayed in this same time zone to the customer, including when they view or edit their booking in the future. - name: tags | type: array | description: List of tags for the booking. - "INDIVIDUAL": For bookings of appointment-based services. Including when the appointment is for a group of participants. - "GROUP": For bookings of individual class sessions. - "COURSE": For course bookings. - name: contactDetails | type: ContactDetails | description: Contact details of the site visitor or [member](https://dev.wix.com/docs/api-reference/crm/members-contacts/members/members/introduction.md) making the booking. - name: contactId | type: string | description: Contact GUID. - name: firstName | type: string | description: Contact's first name. When populated from a standard booking form, this property corresponds to the `name` field. - name: lastName | type: string | description: Contact's last name. - name: email | type: string | description: Contact's email. If no [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/contacts/contact-v4/contact-object.md) with this email exist, a new contact is created. Used to validate coupon usage limitations per contact. If not specified, the coupon usage limitation will not be enforced. (Coupon usage limitation validation is not supported yet). - name: phone | type: string | description: Contact's phone number. - name: fullAddress | type: Address | description: Contact's full address. - ONE-OF: - name: streetAddress | type: StreetAddress | description: Street name, number and apartment number. - name: number | type: string | description: Street number. - name: name | type: string | description: Street name. - name: apt | type: string | description: Apartment number. - name: addressLine | type: string | description: Main address line, usually street and number, as free text. - name: country | type: string | description: Country code. - name: subdivision | type: string | description: Subdivision. Usually state, region, prefecture or province code, according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). - name: city | type: string | description: City name. - name: postalCode | type: string | description: Zip/postal code. - name: addressLine2 | type: string | description: Free text providing more detailed address info. Usually contains Apt, Suite, and Floor. - name: formattedAddress | type: string | description: A string containing the full address of this location. - name: hint | type: string | description: Free text to help find the address. - name: geocode | type: AddressLocation | description: Coordinates of the physical address. - name: latitude | type: number | description: Address latitude. - name: longitude | type: number | description: Address longitude. - name: countryFullname | type: string | description: Country full name. - name: subdivisions | type: array | description: Multi-level subdivisions from top to bottom. - name: code | type: string | description: Subdivision code. Usually state, region, prefecture or province code, according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). - name: name | type: string | description: Subdivision full name. - name: countryCode | type: string | description: Contact's country in [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. - name: status | type: BookingStatus | description: Booking status. A booking is automatically confirmed if the service allows it and an eCommerce order is created. It is automatically declined if there is a double booking and the customer hasn't paid or is eligible for an automatic refund. Currently, only payments with pricing plans are automatically refundable. - enum: - CREATED: The booking was created, but the customer hasn't completed the related eCommerce order yet. - CONFIRMED: The merchant has confirmed the booking and it appears in the business calendar. Merchants can set up their [services](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/introduction.md) to automatically confirm all `PENDING` bookings. - CANCELED: The customer has canceled the booking. Depending on the relevant service's [policy snapshot](https://dev.wix.com/docs/rest/business-solutions/bookings/policies/booking-policy-snapshots/introduction.md) they may have to pay a [cancellation fee](https://dev.wix.com/docs/rest/business-solutions/bookings/pricing/booking-fees/introduction.md). - PENDING: The merchant must manually confirm the booking before it appears in the business calendar. - DECLINED: The merchant has declined the booking before the customer was charged. - WAITING_LIST: Currently, you can't call [Register to Waitlist](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/waitlist/register-to-waitlist.md) for course or appointment bookings, even though this is supported in live sites. - name: paymentStatus | type: PaymentStatus | description: The payment status of the booking. This field automatically syncs with the `paymentStatus` of the corresponding [eCommerce order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/introduction.md) when customers use Wix eCommerce checkout. ### Integration patterns __When using Wix eCommerce checkout__: Wix Bookings automatically syncs the payment status based on the eCommerce order's payment status. Do not manually update this field. __When using custom payment flows__: You can manually update the payment status with [Confirm Booking or Decline Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/confirm-or-decline-booking.md) to reflect the customer's payment state. __For membership/pricing plan payments__: Wix Bookings automatically manages the payment status when customers pay with an active [pricing plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/pricing-plans/introduction.md) subscription. All payment statuses are supported for every booking `status`. - enum: - UNDEFINED: Undefined payment status. - NOT_PAID: The booking isn't paid. - PAID: The booking is fully paid. - PARTIALLY_PAID: The booking is partially paid. - REFUNDED: The booking is refunded. - EXEMPT: The booking is free of charge. - name: selectedPaymentOption | type: SelectedPaymentOption | description: Payment option selected by the customer. If the customer hasn't completed their checkout, they may still change the payment method. Must be one of the payment options offered by the [service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction.md), unless `skipSelectedPaymentOptionValidation` is `true`. When the customer pays with a [Wix eCommerce checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/checkout/introduction.md), this field is required. Otherwise, the Create Booking call fails. For custom checkouts, you don't have to specify this field. - enum: - UNDEFINED: Undefined payment option. - OFFLINE: Offline payment. - ONLINE: Online payment. - MEMBERSHIP: Payment using a Wix Pricing Plan. - MEMBERSHIP_OFFLINE: Customers can pay only in person with a Wix Pricing Plan, while the Wix user must manually redeem the pricing plan in the dashboard. - name: externalUserId | type: string | description: External user GUID that you can provide. - name: revision | type: string | description: Revision number to be used when updating, rescheduling, or cancelling the booking. Increments by 1 each time the booking is updated, rescheduled, or canceled. To prevent conflicting changes, the current revision must be specified when updating the booking. - name: extendedFields | type: ExtendedFields | description: Custom field data for this object. Extended fields must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: formSubmissionId | type: string | description: GUID of the [form submission](https://dev.wix.com/docs/rest/crm/forms/form-submissions/introduction.md) associated with this booking. - name: bookedAddOns | type: array | description: List of [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md) associated with the booking. - name: id | type: string | description: The GUID of the add-on. - name: groupId | type: string | description: The GUID of the add-on group. - name: quantity | type: integer | description: The quantity of booked add-ons. For duration-based add-ons, `quantity` is not applicable. If `quantity` is provided as `1` for a duration-based add-on, it will be accepted but the value will be cleared. If any other value is provided, an `INVALID_ARGUMENT` error will be returned with the message: "Invalid AddOn details: either duration or quantity must be set correctly". - name: depositSelected | type: boolean | description: Whether the customer chooses to pay only the deposit amount upfront. - `true`: The customer pays only the deposit amount upfront. - `false`: The customer pays the full price upfront. Used only when `selectedPaymentOption` is `ONLINE` and the [service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction.md) has a deposit amount set. When the service supports deposit payments and `fullUpfrontPaymentAllowed` is `false`, this field must be `true`. When the service supports deposit payments and `fullUpfrontPaymentAllowed` is `true`, this field can be `true` or `false`. Return type: ValidateBeforeCancelResponse - name: results | type: array | description: Validation results. Contains a result for each booking in the request. - name: bookingId | type: string | description: Booking GUID. Corresponds to the booking in the request. - name: result | type: ValidationResult | description: Validation result for this booking. - name: valid | type: boolean | description: Whether the operation is valid. Set to `true` to allow the operation, or `false` to block it. - name: invalidReason | type: InvalidReason | description: Details about why the validation failed. Populate this when `valid` is `false`. - name: fieldViolations | type: array | description: Field-specific validation issues. Each violation describes a specific field that failed validation. - name: field | type: string | description: Field that failed validation. Use dot notation matching the field path in the request object. For example, `target.startDate` or `booking.payment`. - name: description | type: string | description: Human-readable description of why the field is invalid. This message is displayed to the customer. - name: code | type: string | description: Structured error code for programmatic handling. For example, `PLAN_EXPIRED`, `QUOTA_EXCEEDED`, `BENEFIT_NOT_ELIGIBLE`, or `RESCHEDULE_WINDOW_EXPIRED`. - name: message | type: string | description: General validation error message displayed to the customer. If not provided, a message is auto-generated based on the `fieldViolations`. Provide this when you need a custom, high-level summary. ``` ### Examples ### Validate before cancel - decoded JWT The data payload will include the following object as an encoded JWT. For the purposes of this example, we show the request and response objects decoded. ```curl curl -X POST \ 'https://provider.example.com/v1/validate-before-cancel' \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "data": { "request": { "items": [ { "booking": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "CONFIRMED", "selectedPaymentOption": "FULL", "bookedEntity": { "slot": { "serviceId": "660e8400-e29b-41d4-a716-446655440001", "eventId": "770e8400-e29b-41d4-a716-446655440002", "scheduleId": "880e8400-e29b-41d4-a716-446655440003", "startDate": "2026-02-15T10:00:00Z", "endDate": "2026-02-15T11:00:00Z" } } } } ] }, "metadata": { "requestId": "1674480822.92546993606315181", "identity": { "identityType": "ANONYMOUS_VISITOR", "anonymousVisitorId": "c7808c1d-e6a5-49e5-bcbe-b3fcf2f72d28" }, "instanceId": "bb2b1658-9855-4598-b1e0-48e8cdb7f98a" } }, "aud": "3467d501-9004-498d-9b5c-d50f6d4ede66", "iss": "wix.com", "iat": 1674480823, "exp": 1678080823 }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.bookings.BookingsValidationProvider.validateBeforeCancel(request, metadata) Description: Validates whether a booking can be canceled. Wix calls this method when a customer initiates a cancellation, before the booking status is updated to `CANCELED`. Use this to enforce custom cancellation rules, for example, cancellation fees, minimum notice periods, or membership benefit reversal. If your service returns an error or times out, Wix blocks the cancellation (fail-closed behavior). Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: ValidateBeforeCancelRequest - name: items | type: array | description: Items to validate. - name: booking | type: Booking | description: Booking to validate. - ONE-OF: - name: totalParticipants | type: integer | description: Total number of participants. When creating a booking, use this field only if the relevant service has fixed pricing and doesn't offer [variants and options](https://dev.wix.com/docs/rest/business-solutions/bookings/services/service-options-and-variants/introduction.md). - name: participantsChoices | type: ParticipantChoices | description: Information about the booked service choices and participant count for each choice. When creating a booking, use this field only if the booking includes multiple [service variants](https://dev.wix.com/docs/rest/business-solutions/bookings/services/service-options-and-variants/introduction.md). For example, use this for a spa package booking that includes different service levels: - 2 participants chose "Standard Package". - 1 participant chose "VIP Package". - name: serviceChoices | type: array | description: Information about the booked service choices. Includes the number of participants. - name: numberOfParticipants | type: integer | description: Number of participants for this [variant](https://dev.wix.com/docs/rest/business-solutions/bookings/services/service-options-and-variants/introduction.md). - name: choices | type: array | description: Service choices for these participants. - ONE-OF: - name: custom | type: string | description: Value for one of the choices in the [`CustomServiceOption.choices`](https://example.com) list. Choices are specific values for an option the customer can choose to book. For example, the option `ageGroup` may have these choices: `child`, `student`, `adult`, and `senior`. Each choice may have a different price. - name: duration | type: Duration | description: - name: minutes | type: integer | description: Duration of the service in minutes. Min: 1 minute, Max: 30 days, 23 hours, and 59 minutes - name: name | type: string | description: Name of the duration option. Defaults to the formatted duration e.g. "1 hour, 30 minutes". - name: optionId | type: string | description: GUID of the corresponding option for the choice. For example, the choice `child` could correspond to the option `ageGroup`. In this case, `optionId` is the GUID for the `ageGroup` option. - name: bookedEntity | type: BookedEntity | description: An object describing the bookable entity - either a specific time slot or a recurring schedule. The structure depends on the type of service being booked: __For appointment services__: Use `slot` to book a specific time slot with a service provider. Appointments are typically one-time sessions at a specific date and time. __For class services__: Use `slot` to book a specific class session. Classes are individual sessions that can have multiple participants. __For course services__: Use `schedule` to book an entire course consisting of multiple sessions over time. Courses are recurring, multi-session offerings. Choose the appropriate field based on your service type and booking requirements. - ONE-OF: - name: slot | type: BookedSlot | description: [Booked slot](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings-and-time-slots/time-slots/availability-calendar/query-availability.md). Specify `slot` when creating bookings for: - __Appointment-based services__: Individual sessions with service providers (consultations, treatments). Wix Bookings creates a new session when the booking is confirmed. - __Class services__: Group sessions at specific times (fitness classes, workshops). Wix Bookings links the booking to an existing scheduled session. For course services, specify `schedule` instead of `slot`. - name: serviceId | type: string | description: Service GUID. - name: scheduleId | type: string | description: Schedule GUID. - name: eventId | type: string | description: GUID of the corresponding [event](https://dev.wix.com/docs/rest/business-management/calendar/events-v3/introduction.md). Available for both appointment and class bookings, not available for course bookings. For appointment-based services, Wix Bookings automatically populates `eventId` when the booking `status` changes to `CONFIRMED`. For class bookings, Wix Bookings automatically populates `eventId` upon booking creation. - name: startDate | type: string | description: The start time of this slot in `YYYY-MM-DDThh:mm:ss`, `YYYY-MM-DDThh:mm:ss:SSS`, or `YYYY-MM-DDThh:mm:ss:SSSZZ` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`, `2026-01-30T13:30:00:000`, or `2026-01-30T13:30:00:000-05:00`. - name: endDate | type: string | description: The end time of this slot in `YYYY-MM-DDThh:mm:ss`, `YYYY-MM-DDThh:mm:ss:SSS`, or `YYYY-MM-DDThh:mm:ss:SSSZZ` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`, `2026-01-30T13:30:00:000`, or `2026-01-30T13:30:00:000-05:00`. - name: timezone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database). For example, `America/New_York` or `UTC`. This is the time zone in which the slot was shown to the customer at the time of booking. Wix Bookings ensures that the slot is always displayed in this same time zone to the customer, including when they view or edit their booking in the future. - name: resource | type: BookedResource | description: [Primary resource](https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resources-v2/introduction.md) for the booking. For example, the [staff member](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction.md) providing the service. - name: _id | type: string | description: GUID of the booking's primary resource. - name: name | type: string | description: Resource's name at the time of booking. - name: email | type: string | description: Resource's email at the time of booking. - name: scheduleId | type: string | description: GUID of the schedule belonging to the booking's primary resource. - name: location | type: Location | description: Location where the session takes place. - name: _id | type: string | description: Business location GUID. Available only for locations that are business locations, meaning the `location_type` is `"OWNER_BUSINESS"`. - name: name | type: string | description: Location name. - name: formattedAddress | type: string | description: The full address of this location. - name: formattedAddressTranslated | type: string | description: The full translated address of this location. - name: locationType | type: LocationType | description: Location type. - enum: - UNDEFINED: Undefined location type. - OWNER_BUSINESS: The business address, as set in the site’s general settings. - OWNER_CUSTOM: The address as set when creating the service. - CUSTOM: The address as set for the individual session. - name: resourceSelections | type: array | description: Information about how the customer has selected resources for the booking. Each resource type may have a different selection method. Check `resource` for resource details. - name: resourceTypeId | type: string | description: GUID of the [resource type](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/introduction.md). - name: selectionMethod | type: SelectionMethod | description: Information about how the customer has selected the resource for this resource type. - enum: - SPECIFIC_RESOURCE: The customer explicitly chose a particular resource. - ANY_RESOURCE: The customer explicitly chose "any available resource" for this resource type. - NO_SELECTION: The customer wasn't offered a resource selection or agreement option for this resource type. - name: schedule | type: BookedSchedule | description: [Booked schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/introduction.md). Specify `schedule` when creating bookings for: - __Course services__: Multi-session offerings spanning weeks or months (educational courses, training programs). Wix Bookings enrolls participants in all sessions defined by the course schedule. - name: scheduleId | type: string | description: [Schedule GUID](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/introduction.md). - name: serviceId | type: string | description: Booked service GUID. - name: timezone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database). For example, `America/New_York` or `UTC`. This is the time zone in which the schedule was shown to the customer at the time of booking. Wix Bookings ensures that the schedule is always displayed in this same time zone to the customer, including when they view or edit their booking in the future. - name: tags | type: array | description: List of tags for the booking. - "INDIVIDUAL": For bookings of appointment-based services. Including when the appointment is for a group of participants. - "GROUP": For bookings of individual class sessions. - "COURSE": For course bookings. - name: contactDetails | type: ContactDetails | description: Contact details of the site visitor or [member](https://dev.wix.com/docs/api-reference/crm/members-contacts/members/members/introduction.md) making the booking. - name: contactId | type: string | description: Contact GUID. - name: firstName | type: string | description: Contact's first name. When populated from a standard booking form, this property corresponds to the `name` field. - name: lastName | type: string | description: Contact's last name. - name: email | type: string | description: Contact's email. If no [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/contacts/contact-v4/contact-object.md) with this email exist, a new contact is created. Used to validate coupon usage limitations per contact. If not specified, the coupon usage limitation will not be enforced. (Coupon usage limitation validation is not supported yet). - name: phone | type: string | description: Contact's phone number. - name: fullAddress | type: Address | description: Contact's full address. - ONE-OF: - name: streetAddress | type: StreetAddress | description: Street name, number and apartment number. - name: number | type: string | description: Street number. - name: name | type: string | description: Street name. - name: apt | type: string | description: Apartment number. - name: addressLine | type: string | description: Main address line, usually street and number, as free text. - name: country | type: string | description: Country code. - name: subdivision | type: string | description: Subdivision. Usually state, region, prefecture or province code, according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). - name: city | type: string | description: City name. - name: postalCode | type: string | description: Zip/postal code. - name: addressLine2 | type: string | description: Free text providing more detailed address info. Usually contains Apt, Suite, and Floor. - name: formattedAddress | type: string | description: A string containing the full address of this location. - name: hint | type: string | description: Free text to help find the address. - name: geocode | type: AddressLocation | description: Coordinates of the physical address. - name: latitude | type: number | description: Address latitude. - name: longitude | type: number | description: Address longitude. - name: countryFullname | type: string | description: Country full name. - name: subdivisions | type: array | description: Multi-level subdivisions from top to bottom. - name: code | type: string | description: Subdivision code. Usually state, region, prefecture or province code, according to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). - name: name | type: string | description: Subdivision full name. - name: countryCode | type: string | description: Contact's country in [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. - name: status | type: BookingStatus | description: Booking status. A booking is automatically confirmed if the service allows it and an eCommerce order is created. It is automatically declined if there is a double booking and the customer hasn't paid or is eligible for an automatic refund. Currently, only payments with pricing plans are automatically refundable. - enum: - CREATED: The booking was created, but the customer hasn't completed the related eCommerce order yet. - CONFIRMED: The merchant has confirmed the booking and it appears in the business calendar. Merchants can set up their [services](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/introduction.md) to automatically confirm all `PENDING` bookings. - CANCELED: The customer has canceled the booking. Depending on the relevant service's [policy snapshot](https://dev.wix.com/docs/rest/business-solutions/bookings/policies/booking-policy-snapshots/introduction.md) they may have to pay a [cancellation fee](https://dev.wix.com/docs/rest/business-solutions/bookings/pricing/booking-fees/introduction.md). - PENDING: The merchant must manually confirm the booking before it appears in the business calendar. - DECLINED: The merchant has declined the booking before the customer was charged. - WAITING_LIST: Currently, you can't call [Register to Waitlist](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/waitlist/register-to-waitlist.md) for course or appointment bookings, even though this is supported in live sites. - name: paymentStatus | type: PaymentStatus | description: The payment status of the booking. This field automatically syncs with the `paymentStatus` of the corresponding [eCommerce order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/introduction.md) when customers use Wix eCommerce checkout. ### Integration patterns __When using Wix eCommerce checkout__: Wix Bookings automatically syncs the payment status based on the eCommerce order's payment status. Do not manually update this field. __When using custom payment flows__: You can manually update the payment status with [Confirm Booking or Decline Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/confirm-or-decline-booking.md) to reflect the customer's payment state. __For membership/pricing plan payments__: Wix Bookings automatically manages the payment status when customers pay with an active [pricing plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/pricing-plans/introduction.md) subscription. All payment statuses are supported for every booking `status`. - enum: - UNDEFINED: Undefined payment status. - NOT_PAID: The booking isn't paid. - PAID: The booking is fully paid. - PARTIALLY_PAID: The booking is partially paid. - REFUNDED: The booking is refunded. - EXEMPT: The booking is free of charge. - name: selectedPaymentOption | type: SelectedPaymentOption | description: Payment option selected by the customer. If the customer hasn't completed their checkout, they may still change the payment method. Must be one of the payment options offered by the [service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction.md), unless `skipSelectedPaymentOptionValidation` is `true`. When the customer pays with a [Wix eCommerce checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/checkout/introduction.md), this field is required. Otherwise, the Create Booking call fails. For custom checkouts, you don't have to specify this field. - enum: - UNDEFINED: Undefined payment option. - OFFLINE: Offline payment. - ONLINE: Online payment. - MEMBERSHIP: Payment using a Wix Pricing Plan. - MEMBERSHIP_OFFLINE: Customers can pay only in person with a Wix Pricing Plan, while the Wix user must manually redeem the pricing plan in the dashboard. - name: externalUserId | type: string | description: External user GUID that you can provide. - name: revision | type: string | description: Revision number to be used when updating, rescheduling, or cancelling the booking. Increments by 1 each time the booking is updated, rescheduled, or canceled. To prevent conflicting changes, the current revision must be specified when updating the booking. - name: extendedFields | type: ExtendedFields | description: Custom field data for this object. Extended fields must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: formSubmissionId | type: string | description: GUID of the [form submission](https://dev.wix.com/docs/rest/crm/forms/form-submissions/introduction.md) associated with this booking. - name: bookedAddOns | type: array | description: List of [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md) associated with the booking. - name: _id | type: string | description: The GUID of the add-on. - name: groupId | type: string | description: The GUID of the add-on group. - name: quantity | type: integer | description: The quantity of booked add-ons. For duration-based add-ons, `quantity` is not applicable. If `quantity` is provided as `1` for a duration-based add-on, it will be accepted but the value will be cleared. If any other value is provided, an `INVALID_ARGUMENT` error will be returned with the message: "Invalid AddOn details: either duration or quantity must be set correctly". - name: depositSelected | type: boolean | description: Whether the customer chooses to pay only the deposit amount upfront. - `true`: The customer pays only the deposit amount upfront. - `false`: The customer pays the full price upfront. Used only when `selectedPaymentOption` is `ONLINE` and the [service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction.md) has a deposit amount set. When the service supports deposit payments and `fullUpfrontPaymentAllowed` is `false`, this field must be `true`. When the service supports deposit payments and `fullUpfrontPaymentAllowed` is `true`, this field can be `true` or `false`. Return type: PROMISE - name: results | type: array | description: Validation results. Contains a result for each booking in the request. - name: bookingId | type: string | description: Booking GUID. Corresponds to the booking in the request. - name: result | type: ValidationResult | description: Validation result for this booking. - name: valid | type: boolean | description: Whether the operation is valid. Set to `true` to allow the operation, or `false` to block it. - name: invalidReason | type: InvalidReason | description: Details about why the validation failed. Populate this when `valid` is `false`. - name: fieldViolations | type: array | description: Field-specific validation issues. Each violation describes a specific field that failed validation. - name: field | type: string | description: Field that failed validation. Use dot notation matching the field path in the request object. For example, `target.startDate` or `booking.payment`. - name: description | type: string | description: Human-readable description of why the field is invalid. This message is displayed to the customer. - name: code | type: string | description: Structured error code for programmatic handling. For example, `PLAN_EXPIRED`, `QUOTA_EXCEEDED`, `BENEFIT_NOT_ELIGIBLE`, or `RESCHEDULE_WINDOW_EXPIRED`. - name: message | type: string | description: General validation error message displayed to the customer. If not provided, a message is auto-generated based on the `fieldViolations`. Provide this when you need a custom, high-level summary. ``` ### Examples ### validateBeforeCancel ```javascript import { bookingsValidation } from '@wix/bookings/service-plugins'; async function validateBeforeCancel(request,metadata) { const response = await bookingsValidation.validateBeforeCancel(request,metadata); }; ``` ### validateBeforeCancel (with elevated permissions) ```javascript import { bookingsValidation } from '@wix/bookings/service-plugins'; import { auth } from '@wix/essentials'; async function myValidateBeforeCancelMethod(request,metadata) { const elevatedValidateBeforeCancel = auth.elevate(bookingsValidation.validateBeforeCancel); const response = await elevatedValidateBeforeCancel(request,metadata); } ``` ### validateBeforeCancel (self-hosted) 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.md). ```javascript import { createClient } from '@wix/sdk'; import { bookingsValidation } from '@wix/bookings/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { bookingsValidation }, // Include the auth strategy and host as relevant }); async function validateBeforeCancel(request,metadata) { const response = await myWixClient.bookingsValidation.validateBeforeCancel(request,metadata); }; ``` ---