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:
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.
lineItem
, or in an other
area of the cart or checkout page.Follow these steps to begin implementing your service plugin.
You can implement this service plugin with the following frameworks:
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.
Use validations.provideHandlers()
to define the following handler functions that implement your custom business logic. Make sure you define all required functions.
Function | Required |
---|---|
getValidationViolations() | Yes |
Below is an example for implementing the Validations service plugin in your code.
This is the basic code structure for implementing the Validations service plugin with the Wix CLI:
import { validations } from "@wix/ecom/service-plugins";
validations.provideHandlers({
getValidationViolations: async (payload) => {
const { request, metadata } = payload;
// Add your logic here
},
});
This is the basic code structure for implementing a self-hosted Validations service plugin:
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);
});
To configure and customize your service plugin, you need to provide important details in the plugin.json
configuration file.
If you created your service plugin extension with the CLI, required fields are automatically populated for you.
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
.
Whether to validate the cart page in addition to the checkout page. Default: false
{
"deploymentUri": "https://my-validations-app.com/",
"validateInCart": true
}
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:
validateInCart
parameter to true
in the Ecom Validations Integration's config file.function getValidationViolations(
payload: GetValidationViolationsEnvelope,
): GetValidationViolationsResponse | Promise<GetValidationViolationsResponse>;
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",
},
},
},
],
};
},
});