About the Bookings Validation Service Plugin

The Bookings Validation service plugin lets you implement custom validation logic for booking operations. When a customer attempts to create, cancel, or reschedule a booking on a Wix site, Wix calls your validation method before executing the operation. Your implementation can approve or reject the operation based on your own business rules.

With the Bookings Validation service plugin, you can:

• Enforce membership and pricing plan limits on booking creation and rescheduling, including validation against plan limits and external calendar availability.
• Apply custom cancellation policies, such as minimum notice periods or cancellation fees.
• Implement fraud prevention by blocking suspicious booking attempts.
• Coordinate validation rules across all bookings in a multi-service package.

Validation flow

Wix Bookings calls your service plugin at specific points during booking operations. The flow differs slightly depending on whether the operation involves a single-service booking or a multi-service package.

Single-service booking operations

For a single-service booking, Wix calls the validation method that corresponds to the operation being performed.

1. A customer initiates a booking operation (create, cancel, or reschedule).
2. Wix calls your corresponding validation method with the booking details.
3. Your implementation evaluates the request and returns a validation result.
4. If valid is true, Wix continues with the operation.
5. If valid is false, Wix blocks the operation and displays your error message to the customer.

Multi-service booking operations

Multi-service bookings are packages containing multiple related bookings, such as a spa day that includes a massage, facial, and manicure.

1. A customer initiates an operation on a multi-service booking package.
2. Wix calls your multi-service validation method with all bookings in the package.
3. Your implementation evaluates the request and returns a validation result for each booking.
4. If any booking in the package fails validation, the entire operation is blocked.
5. Error messages from failed validations are displayed to the customer.

Error and timeout behavior

Each method handles errors and timeouts differently:

Method	On error or timeout
Validate Before Create	Operation is blocked (fail-closed).
Validate Before Cancel	Operation is blocked (fail-closed).
Validate Before Reschedule	Operation continues (fail-open).
Validate Before Create Multi Service	Operation is blocked (fail-closed).
Validate Before Cancel Multi Service	Operation is blocked (fail-closed).
Validate Before Reschedule Multi Service	Operation continues (fail-open).

Writing error messages

The FieldViolation.description and InvalidReason.message values are displayed to the customer when validation fails. Make them clear and actionable, and avoid technical jargon. The FieldViolation.code field is optional and intended for programmatic handling by your system, not for display to customers.

Before you begin

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

• Your implementation should respond as quickly as possible to avoid timeouts.
• Multiple service plugin providers can be registered for the same validation target. When this happens, all providers are called concurrently. If any provider rejects the operation or returns an error, the operation is blocked.
• Booking data sent to your validation method is sanitized before transmission. All fields in contactDetails (including firstName, lastName, email, phone, and fullAddress) are redacted. The name and email fields for primary and additional resources in bookedEntity.slot.resource are also redacted.
• For bulk create operations, validation is per item. Items that pass continue normally, and items that fail are excluded from the operation. If your response omits a result for any item, that item is treated as valid. For single-service and multi-service operations, validation follows all-or-nothing semantics.

Use cases

• Enforce limits or validate against an external system.
• Apply cancellation policies.
• Validate multi-service bookings.

Terminology

• Validation target: The booking operation your service plugin handles. Supported targets are CREATE, CANCEL, RESCHEDULE, CREATE_MULTI_SERVICE, CANCEL_MULTI_SERVICE, and RESCHEDULE_MULTI_SERVICE.
• Validation result: Your response to a validation request. Contains a valid boolean and, when valid is false, an InvalidReason with optional error details.
• Field violation: A specific field-level error in a validation result. Describes which field failed validation and why. Use dot notation for the field path, such as target.startDate.

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

See also

• About Service Plugin Extensions
• Add a Service Plugin Extension With the CLI
• Add a Self-hosted Service Plugin With the SDK
• Add Self-hosted Service Plugin Extensions with REST
• Bookings APIs