About the Validations Service Plugin

As a validations provider, you can integrate with Wix to allow site owners and collaborators to validate a site visitor's cart and checkout. For example, you can validate a specific line item’s quantity if the quantity per order is limited. Site owners and collaborators can either write their own custom validation logic, or integrate with a 3rd-party validations provider.

The integration is done via an app in the Wix App Market and by implementing the Validations service plugin. After the app is installed on a site, Wix triggers a call to your service whenever the site needs to validate a cart or checkout. If there aren't any validation violations, the endpoint should return an object containing an empty array.

Using the service plugin, you can design your app to validate a cart and checkout for your merchant's customers, including:

  • Minimum cart value.
  • Age of a customer before they proceed to checkout.
  • Line item quantity limit.
  • Valid coupon code.
  • Specific items to ship only to specific regions.
  • Restrict purchases to site members only.
  • Close the checkout on certain days.

Before you begin

By default, the Validations service plugin only validates a site visitor's checkout. If you want to also validate a site visitor's cart, set the validateInCart parameter to true in the service plugin's configuration.

Terminology

  • Severity: How severe the violation is. The violations are shown on the cart and checkout pages. A warning is displayed as yellow, and allows a site visitor to proceed with caution. An error is displayed as red, and doesn't allow a site visitor to proceed with the eCommerce flow.
  • Subscription Option: A store owner can create subscriptions to sell their products on a recurring basis. A line item can be a subscription.
  • Target: Target location on a checkout or cart page where the violation will be displayed. The target violation can either be in a particular lineItem, or in an other area of the cart or checkout page.
  • Violations: A list of any validation violations in a site visitor's cart or checkout.

Get started

Follow these steps to begin implementing your service plugin.

Choose a framework

You can implement this service plugin with the following frameworks:

Configure your service plugin

To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can configure your plugin in the Wix Dev Center. For details, see Validations Extension Configuration.

Define handler functions

Use validations.provideHandlers() to define the following handler functions that implement your custom business logic. Make sure you define all required functions.

FunctionRequired
getValidationViolations()Yes

Code examples

Below is an example for implementing the Validations service plugin in your code.

CLI: Basic code structure

This is the basic code structure for implementing the Validations service plugin with the Wix CLI:

Copy
import { validations } from "@wix/ecom/service-plugins"; validations.provideHandlers({ getValidationViolations: async (payload) => { const { request, metadata } = payload; // Add your logic here }, });

Self-hosted: Basic code structure

This is the basic code structure for implementing a self-hosted Validations service plugin:

Copy
import { createClient } from '@wix/sdk'; import { validations } from '@wix/ecom/service-plugins' const wixClient = createClient({ auth: { appId: <YOUR_APP_ID>, publicKey: <YOUR_APP_PUBLIC_KEY> }, modules: { validations } }); wixClient.validations.provideHandlers({ getValidationViolations: async (payload) => { const { request, metadata } = payload; // Add your logic here } }); // Implement a router to process all requests express.post('/plugins-and-webhooks/*', (req, res) => { wixClient.process(req); });

See also

Did this help?

Extension Config


To configure and customize your service plugin, you need to provide important details in the plugin.json configuration file.

Note

If you created your service plugin extension with the CLI, required fields are automatically populated for you.

Configuration Params
deploymentUristring

Required. Base URI where the endpoints are called. Wix appends the endpoint path to the base URI. For example, to call the Get Validation Violations endpoint at https://my-validations.com/v1/get-violations, the base URI you provide here is https://my-validations.com.


validateInCartboolean

Whether to validate the cart page in addition to the checkout page. Default: false

Validations Extension Config
JSON
{ "deploymentUri": "https://my-validations-app.com/", "validateInCart": true }
Did this help?

getValidationViolations( )


Important: This is a handler function. Implement it only as part of the service plugin.


This method retrieves validation violations from your app.

Wix calls this method when certain actions are performed on a visitor's cart and checkout. For example, when an item is added to the cart, or when a coupon is added to a checkout. This method validates a visitor's cart and checkout, and returns any validation violations (using the structure provided by Wix eCommerce). Site visitors can see the validation violations in their cart and checkout pages. If there aren't any validation violations, the method returns an object containing an empty list.

Notes:

  • Do not call the Estimate Cart Totals, Estimate Current Cart Totals or Get Checkout methods from your implementation code for Get Validation Violations. Doing so will result in an error.
  • By default, this method only retrieves validation violations from a visitor's checkout. If you want to also retrieve validation violations from a visitor's cart, set the validateInCart parameter to true in the Ecom Validations Integration's config file.
Method Declaration
Copy
function getValidationViolations(
  payload: GetValidationViolationsEnvelope,
): GetValidationViolationsResponse | Promise<GetValidationViolationsResponse>;
Method Parameters
payloadGetValidationViolationsEnvelope
Returns
Return Type:GetValidationViolationsResponse | Promise<GetValidationViolationsResponse>
Example of a `violations` return value
JavaScript
import { validations } from "@wix/ecom/service-plugins"; validations.provideHandlers({ getValidationViolations: async (payload) => { const { request, metadata } = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: violations: [ { description: "You must purchase at least 100 items.", severity: "WARNING", target: { other: { name: "OTHER_DEFAULT", }, }, }, ], }; }, });
Did this help?