Introduction

The Validations service plugin (formerly SPI) allows 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.

Wix eCommerce calls getValidationViolations() to retrieve any violations in a site visitor's cart and checkout. The custom validation plugin code validates the request, and returns any validation violation data in a site visitor's cart and checkout (using the structure provided by Wix eCommerce). If there aren't any validation violations, the endpoint should return an object containing an empty array. Site visitors can see validation violations in their cart and checkout pages. For example, see the images below:

The image below shows a cart page with both a general validation violation warning and a line item validation violation warning.

Cart page warning

The images below show a checkout page with both a general validation violation error and a line item validation violation error.

The general violation error appears at the top of the checkout page:

Checkout page errors - top

The error appears again above the Place Order & Pay button at the end of the page. The button is disabled until the errors are resolved.

Checkout page errors - bottom

For a step-by-step tutorial, see Validation Violations service plugin.

Future functionality includes validating products and orders.

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 config file.

To add a service plugin

  1. Add the plugin to your site.
  2. Update the getConfig() function in the -config.js file that is added to your site during step 1.
  3. Update the getValidationViolations() function in the .js file that is added to your site during step 1.

Use Cases

With the Validations service plugin you can define the validations for a cart and checkout that fit your site's needs. Possible validations include:

  • Minimum subtotal amount to qualify for free shipping.
  • Age of a customer before they proceed to checkout.
  • Specific items to ship only to specific regions.
  • Restrict purchases to site members only.
  • Close checkout on certain days.

Terminology

TermDefinition
SeverityHow 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 OptionA store owner can create subscriptions to sell their products on a recurring basis. A line item can be a subscription.
TargetTarget 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.
ViolationsA list of any validation violations in a site visitor's cart or checkout.
Did this help?

getConfig( )


Retrieves the configuration of your validations plugin.

Set your validations configuration in the return of the getConfig() function. Wix calls this function when you publish your site. Changes to the configuration don't take effect until you publish your site.

By default, the Validations service plugin only validates a site visitor's checkout. To also validate a site visitor's cart, set validateInCart to true.

Where to find getConfig()

When you add the Validations service plugin, a folder is automatically added to your site. Use the -config.js file in the folder to set the default configuration for your implementation of the service plugin.

For more information on setting your configuration, see Tutorial: Validations Service Plugin.

Method Declaration
Copy
function getConfig(): Promise<ValidationsConfigResponse>;
Request
This method does not take any parameters
Returns
Return Type:Promise<ValidationsConfigResponse>
Example of a configuration file
JavaScript
// Place this code in the <my-extension-name>-config.js file // in the 'ecom-validations' folder of the // Custom Extensions section on your site. export function getConfig() { return { validateInCart: true, }; }
Did this help?

getValidationViolations( )


Retrieves any validation violations in a site visitor's cart or checkout.

The getValidationViolations function validates a site visitor's cart or checkout and returns any validation violations. Site visitors can see the validation violations in their cart and checkout pages. If there aren't any validation violations, the endpoint returns an object containing an empty list.

The function is automatically called by Wix eCommerce when certain actions are performed on a cart or checkout. For example, when an item is added to a cart, or when a coupon is added to a checkout.

Note: 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 config file.

Where to find getValidationViolations()

When you add the Validations service plugin, a folder is automatically added to your site. Use the .js file in the folder to write the code to determine which validation violations to retrieve.

For more information on customizing your checkout validations plugin, see Tutorial: Validations Service Plugin.

Method Declaration
Copy
function getValidationViolations(
  options: Options,
  context: Context,
): Promise<GetValidationViolationsResponse>;
Method Parameters
optionsOptionsRequired

Validation options.


contextContextRequired

Metadata about the request.

Returns
Return Type:Promise<GetValidationViolationsResponse>
Get Validation Violations

This example validates a cart and checkout. The quantity of gold rings is limited, and the site visitor isn't allowed to purchase more than 5.

JavaScript
const goldRingItemId = "37e5db61-d37d-442d-1bf5-ae755f82020b"; export const getValidationViolations = async (options, context) => { const lineItems = options.validationInfo.lineItems; let violations = []; if (hasExcessiveGoldRingQuantity(lineItems)) { const source = options.sourceInfo.source; const severity = getSourceSeverity(source); const target = { lineItem: { name: "LINE_ITEM_DEFAULT", _id: findGoldRingLineItemId(lineItems), }, }; const description = "You can't purchase more than 5 gold rings."; const violation = createViolation(severity, target, description); violations.push(violation); } return { violations }; }; function getSourceSeverity(source) { if (source === "CART") { return "WARNING"; } else { return "ERROR"; } } function hasExcessiveGoldRingQuantity(lineItems) { for (const lineItem of lineItems) { if ( lineItem.catalogReference.catalogItemId === goldRingItemId && lineItem.quantity > 5 ) { return true; } } return false; } function findGoldRingLineItemId(lineItems) { for (const lineItem of lineItems) { if (lineItem.catalogReference.catalogItemId === goldRingItemId) { return lineItem._id; } } return undefined; } function createViolation(severity, target, description) { return { severity, target, description }; }
Did this help?