# About the Wix eCommerce Validations Service Plugin

<blockquote class="important">

__Important:__ 
When developing websites or building apps with Blocks, use [Velo service plugins](fallback::https://dev.wix.com/docs/velo/events-service-plugins/about-events-service-plugins-and-the-sdk).

</blockquote>

As a validations provider, you can integrate with Wix to allow Wix users 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. Wix users 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](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions). 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 method 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.

## Use Cases

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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::d8639f57-736d-40d0-a3ba-3728ab3e62a5slug::sample-flow#wix-ecommerce_validations-integration-spi_sample-flow_validate-a-line-item's-quantity*fallback::https://dev.wix.com/api/rest/wix-ecommerce/validations-integration-spi/sample-flow#wix-ecommerce_validations-integration-spi_sample-flow_validate-a-line-item's-quantity).
+ [Valid coupon code](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::d8639f57-736d-40d0-a3ba-3728ab3e62a5slug::sample-flow#wix-ecommerce_validations-integration-spi_sample-flow_validate-a-coupon-code-for-a-wix-checkout*fallback::https://dev.wix.com/api/rest/wix-ecommerce/validations-integration-spi/sample-flow#wix-ecommerce_validations-integration-spi_sample-flow_validate-a-coupon-code-for-a-wix-checkout).
+ Specific items to ship only to specific regions.
+ Restrict purchases to site members only.
+ Close the checkout on certain days. 


::::tabs
:::REST_TAB

## Get started

To enable Wix to communicate with your app:
1. Go to [Extensions](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions) in your app's dashboard.
1. Click **Create Extension** in the top right.
1. Filter by **eCommerce** in the left menu, then find **Ecom Validations** and click **Create**.
1. Provide the following configuration:

| Name | Type | Description                                                                                                                                                                                                                                                                  |
| --- | --- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `deploymentUri`|string| 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`. |
| `componentName`|string| A unique name for this component. This is an internal name that will only appear in the app dashboard.                                                                                                                                                                          |
| `validateInCart`|boolean| Whether to validate the cart page in addition to the checkout page. Default: `false`                                                                                                                                                                                         |

:::
:::SDK_TAB

## Get started

Follow these steps to begin implementing your service plugin.

### Step 1 | Choose a framework

You can implement this service plugin with the following [frameworks](fallback::https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks):

+ **Wix CLI:** Learn how to [implement a service plugin with the CLI and the SDK](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli).
+ **Self-hosted:** Learn how to [implement a self-hosted service plugin with the SDK and the Wix Dev Center](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk).

### Step 2 | 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](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-1--add-a-service-plugin-extension-to-your-app). For details, see [Validations Extension Configuration](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/extensions/validations/validations-integration-service-plugin/extension-config).

### Step 3 | Define handler functions

Use [`validations.provideHandlers()`](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-4--define-handler-functions) to define the following handler functions that implement your custom business logic. Make sure you define all required functions.

| Function                    | Required       |
|-----------------------------|----------------|
| [`getValidationViolations()`](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/extensions/validations/validations-integration-service-plugin/get-validation-violations)    | 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:

```js
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:

```js
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);
});
  
```

:::
::::


## Terminology

- **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](fallback::https://support.wix.com/en/article/wix-stores-selling-product-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. 


## See also

+ [About Service Plugin Extensions](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions)
+ [Add a Service Plugin Extension With the CLI](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli)
+ [Add a Self-hosted Service Plugin With the SDK](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk)
+ [Add Self-hosted Service Plugin Extensions with REST](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest)

# 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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::d8639f57-736d-40d0-a3ba-3728ab3e62a5slug::get-validation-violations*fallback::https://dev.wix.com/api/rest/wix-ecommerce/validations-integration-spi/get-validation-violations) service plugin request to your app. 

3. Your server validates the request. If the coupon code is valid, the validation is successful and the service plugin 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:
    
    ```json
    {
      "violations": [{
        "severity": "ERROR",
        "target": {
          "other": {
            "name": "OTHER_DEFAULT"
          }
        },
        "description": "Can't apply coupon because minimum cart value has not been reached.",
      }]
    } 
    ```

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, 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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::d8639f57-736d-40d0-a3ba-3728ab3e62a5slug::get-validation-violations*fallback::https://dev.wix.com/api/rest/wix-ecommerce/validations-integration-spi/get-validation-violations) service plugin 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:
    
    ```json
    {
      "violations": {
        "severity": "ERROR",
        "target": {
          "line_item": {
            "name": "LINE_ITEM_DEFAULT",
            "id": "00000000-0000-0000-0000-000000000001"
          }
        },
        "description": "Can't proceed with checkout. Remove 1 case of white wine from your cart.",
      }
    }
    ```

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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::d8639f57-736d-40d0-a3ba-3728ab3e62a5slug::get-validation-violations*fallback::https://dev.wix.com/api/rest/wix-ecommerce/validations-integration-spi/get-validation-violations) service plugin 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.

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

Picasso

GraphQL (Alpha)