About the Wix eCommerce Validations SPI

As a validation service provider, you can integrate your service with Wix's cart and checkout to allow merchants to request and use your services on their Wix sites. By integrating your service with Wix, the validations are performed on the site visitor's cart and checkout.

The integration is done via an app in the Wix App Market (created in the Wix Developers Center) and the Wix Validations SPI.

Future functionality includes validating products and orders.

Learn more about implementing an SPI with Wix.

Before you begin

By default, the Validations SPI 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 extension’s configuration file in the Wix Developers Center.

Use Cases

Using the SPI, 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.

Configuration

To enable Wix to communicate with your app:

1. Go to the Extensions tab in the Wix Developers Center.
2. Click Create Extension in the top right.
3. Filter by eCommerce in the left menu, then find Ecom Validations and click Create.
4. Provide the following configuration:

Name	Type	Description
deploymentUri	string	Required. Base URI which Wix eCommerce will call to retrieve the validation violations. For example, "deploymentUri": "https://my-validations.com"
componentName	string	A unique name for this component. This is an internal name that will only appear in the Dev Center.
validateInCart	boolean	Whether to validate the cart page in addition to the checkout page. Default: false

Terminology

Term	Definition
Merchant	Business that offers products on their Wix site to customers.
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.
Validation Service Provider	A 3rd-party app that implements custom logic to validate the site's cart or checkout.
Violations	A list of any validation violations in a site visitor's cart or checkout.
Wix site owner	The person managing the merchant's Wix site.

Validation Violations: Sample Use Cases & Flows

This article presents sample flows your app can support. You aren't limited to this exact flow, but it can be a helpful jumping off point as you plan your Validations integration.

Validate a coupon code for a Wix checkout

1. A site visitor adds a coupon code to their Wix checkout.

2. Wix sends a Get Validation Violations SPI request to your app.

3. Your server validates the request. If the coupon code is valid, the validation is sucessful and the SPI returns an object containing an empty list. If the coupon isn't valid, the validation isn't successful. In this case, Wix eCommerce expects an object containing the validation violations, and the severity and target of the violations.

   Example of a violations response from your app:

   Copy

   1
   {
   2
     "violations": [{
   3
       "severity": "ERROR",
   4
       "target": {
   5
         "other": {
   6
           "name": "OTHER_DEFAULT"
   7
         }
   8
       },
   9
       "description": "Can't apply coupon because minimum cart value has not been reached.",
   10
     }]
   11
   }

4. With this validation violation, the site visitor can't proceed with the checkout.

Validate a line item's quantity

In this flow, due to limited quantity of white wine, a site visitor can't add more than 5 cases of white wine to their cart.

App configuration prerequisites

When configuring your app in the Wix Developers Center, use these sample settings:

When configuring your app in the Wix Developers Center, set the validateInCart property to true in the extension’s configuration file. This validates a site visitor's cart in addition to a site visitor's checkout.

The flow

1. A site visitor adds 6 cases of white wine to their cart, which exceeds the quantity that is permitted for this line item.

2. Wix sends a Get Validation Violations SPI request to your app.

3. Your server validates the request and finds it unsuccessful. Wix eCommerce expects an object containing the validation violations, and the severity and target of the violations.

   Example of a violations response from your app:

   Copy

   1
   {
   2
     "violations": {
   3
       "severity": "ERROR",
   4
       "target": {
   5
         "line_item": {
   6
           "name": "LINE_ITEM_DEFAULT",
   7
           "id": "00000000-0000-0000-0000-000000000001"
   8
         }
   9
       },
   10
       "description": "Can't proceed with checkout. Remove 1 case of white wine from your cart.",
   11
     }
   12
   }

4. After this validation violation, the site visitor removes 1 case of white wine to proceed to Wix Checkout.

5. Again Wix sends a Get Validation Violations SPI request to your app.

6. Your server validates the request and finds it successful. In this case, Wix eCommerce expects an object containing an empty list.