Tutorial: Validations Custom Extension

Wix Custom Extensions allow you to implement custom logic to change how your site behaves and displays using Velo SPIs. For example, when you set up a Wix eCommerce site, there are a small number of validations to choose from. The validations custom extension allows you to implement your own validations and options using code. You can also connect your site to validation providers not currently supported by Wix. Any violations to these validations are displayed on your store's Checkout and Cart pages.

Custom extensions are implemented using Velo SPIs. You can manage extended services from your site's dashboard, and they behave just like the ones Wix already supports. Learn more about using Custom App Extensions Using SPIs.

With the Validations SPI you can define the validations for a cart or 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 the checkout on certain days.

Introduction

This tutorial explains how to set up and implement a validation extension on your site using Velo. We created an example to demonstrate how you can use custom extensions to validate your checkout and cart pages. We use the example of wholesale store where a customer must purchase a minimum total of 300 items, and if a customer purchase toothbrushes, then they must purchase at least 200 toothbrushes.

The process has 3 steps:

  1. Create a new validations extension on our site.
  2. Implement our extension with custom code.
  3. Deploy the extension.

Step 1: Create a new validation extension

The first step in setting up your new extension is to add it to your site. This process creates a new folder in the Custom Extensions section of the Velo sidebar (Wix Editor), or the /src/backend/spi section of the Wix IDE Explorer (Wix Studio), which contains the files for your code.

  1. Add the Wix Stores app to your site.

  2. Enable coding:

    • Wix Studio: If necessary, click and then Start Coding.
    • Wix Editor: Enable Velo Dev Mode, and then click the Public & Backend tab in the Velo sidebar.

  3. Go to the Custom Extensions section:

    • Wix Studio: Click Packages & Apps.
    • Wix Editor: Scroll down to the Custom Extensions panel at the bottom of the sidebar.

  4. Hover over Custom Extensions and click , then click Add eCommerce Validation SPI.

  5. Follow the prompts to add the extension and accept any terms and conditions that display.

  6. Enter a name for your integration and click Add & Edit Code. The name can't contain spaces or special characters.

  7. Wix Studio: Open the Wix IDE, and go to /src/backend/spi/ecom-validations. If your Custom Extension doesn't appear, try refreshing both the Studio Editor and the Wix IDE.

  8. Publish your site.

Step 2: Implement the extension

The procedure in the previous step creates a folder in the Custom Extensions section of the Velo sidebar (Wix Editor), or in the Wix IDE's Explorer (Wix Studio). The name of the folder is based on the extension you chose. Inside this is another folder with the name of the extension you set up. This folder contains 2 files, minimums.js and minimums-config.js. We implement the custom code for our extension in these files.

minimum-config.js

This file is where write the code for setting up the extension's configuration.

The code in this file defines a function named getConfig() that returns an object containing the values used to display the eCommerce validations on your site's dashboard. By default, the Validations SPI only validates a site visitor's checkout.

In our example, we want to also validate a site visitor's cart, so we set the validateInCart parameter to true in the custom extension's configuration file.

This file is where write the code for setting up the extension's configuration. The code in this file defines a function named getConfig() that returns an object containing the values used to display the eCommerce validations on your site's dashboard. By default, the Validations SPI only validates a site visitor's checkout. In our example, we want to also validate a site visitor's cart, so we set the validateInCart parameter to true in the custom extension's configuration file.

Copy
1
import * as ecomValidations from 'interfaces-ecommerce-v1-validations-provider';
2


3
export function getConfig() {
4
  return {validateInCart: true};
5
}

minimum.js

This file is where we write the code for validating the minimum total item quantity, and the minimum quantity of toothbrushes (a line item's quantity). A customer must purchase a total of at least 300 items, and if the customer is purchasing toothbrushes, they must purchase at least 200 toothbrushes. If there are any violations to these validations, they are shown in a site visitor's cart and checkout pages(see images in step 3).

The code in this file defines a function named getValidationViolations(). This function is called by Wix eCommerce to retrieve any violations to the validations provided by our extension. The function accepts the following parameter:

options: An object containing data about the source of the request, and the cart or checkout information to validate. This information includes line items, gift cards, applied discounts, shipping information, and billing information. For more details, see the SPI Reference.

The getValidationViolations() function returns an array of validation objects (any validation violations in a site visitor's cart or checkout). These validation violations are displayed in the site visitor's cart and checkout pages. If there are no validation violations, the response is an object containing an empty list.

This file is where we write the code for validating the minimum total item quantity, and the minimum quantity of toothbrushes (a line item's quantity). A customer must purchase a total of at least 300 items, and if the customer is purchasing toothbrushes, they must purchase at least 200 toothbrushes. If there are any violations to these validations, they are shown in a site visitor's cart and checkout pages(see images in step 3). The code in this file defines a function named getValidationViolations(). This function is called by Wix eCommerce to retrieve any violations to the validations provided by our extension. The function accepts the following parameter:

options: An object containing data about the source of the request, and the cart or checkout information to validate. This information includes line items, gift cards, applied discounts, shipping information, and billing information. For more details, see the SPI Reference.

The getValidationViolations() function returns an array of validation objects (any validation violations in a site visitor's cart or checkout). These validation violations are displayed in the site visitor's cart and checkout pages. If there are no validation violations, the response is an object containing an empty list.

The code:

Copy
1
import * as ecomValidations from 'interfaces-ecommerce-v1-validations-provider';
2


3
export const getValidationViolations = async (options, context) => {
4
  let violations = [];
5
  const source = options.sourceInfo.source;
6
  const severity = source == ecomValidations.Source.CART ? ecomValidations.Severity.WARNING : ecomValidations.Severity.ERROR;
7


8
  const bambooDescription = "You must purchase at least 200 Bamboo Toothbrushes."
9
  const bambooLineItem = options.validationInfo.lineItems.find(lineItem => isBambooTooth(lineItem.catalogReference?.catalogItemId));
10
  if (bambooLineItem != undefined) {
11
    const quantity = bambooLineItem.quantity;
12
    if (quantity > 0 && quantity < 200) {
13
      violations.push({
14
        severity,
15
        target: { lineItem: { name: ecomValidations.NameInLineItem.LINE_ITEM_DEFAULT, _id: bambooLineItem._id } },
16
        description: bambooDescription
17
      });
18
    }
19
  }
20


21
  const cartQuantityDescription = "You must purchase a minimum of 300 items."
22
  const cartQuantity = options.validationInfo.lineItems.reduce((partialSum, lineItem) => partialSum + lineItem.quantity, 0);
23
  if (cartQuantity < 300) {
24
    violations.push({
25
      severity,
26
      target: { other: { name: ecomValidations.NameInOther.OTHER_DEFAULT } },
27
      description: cartQuantityDescription
28
    });
29
  }
30
  return { violations };
31
};
32


33
const isBambooTooth = (catalogItemId) => {
34
  const bambooToothCatalogItemId = "cd59cd36-b6d2-2cf3-9d48-81793a7bdbbd";
35
  const ifBambooTooth = catalogItemId != undefined && (catalogItemId == bambooToothCatalogItemId);
36
  return ifBambooTooth;
37
}

Line 1-3: First we import the eCom validations provider module. Then we export the getValidationViolations() function where we set the custom logic for our validations.
Lines 4-5: We declare our variables.
Line 6: For the severity, if the source of the validation is a CART, then we want any violations to the cart to display as a warning. Otherwise (if the source of the validation is a checkout), then we want any violations to the checkout to display as an error.
Line 7: Set the violation description that will be displayed when there is a violation to the toothbrush validation.
Lines 9-11: Check the line items in the cart or checkout to see if they contain a toothbrush. We do this by calling a function that we create later in our code to check whether the catalog ID of the toothbrush in the cart or checkout matches the catalog item ID in the list of catalog items. If it matches, get the toothbrush's quantity.
Lines 12-20: If the toothbrush's quantity is between 1-200, set the severity, target, and description of the violation and push them into a violations array. The target is set to the line item's default since the validation violation is on a specific line item.
Line 21: Set the violation description that will be displayed when there is a violation to the minimum total item quantity validation.
Lines 22- 32: Calculate the cart's total quantity. If the quantity is less than 300, set the severity, target, and description of the violation and push them into a violations array. The target is set to the other (general) validation violation default since the validation violation is not on a specific line item, rather on the total item quantity of the cartcheckout.
Lines 33- 37: Here we create a function to check whether the ID we pass into the function (the catalog ID of the toothbrush in the cart or checkout) matches the catalog item ID in the list of catalog items.

Line 1-3: First we import the eCom validations provider module. Then we export the getValidationViolations() function where we set the custom logic for our validations. Lines 4-5: We declare our variables. Line 6: For the severity, if the source of the validation is a CART, then we want any violations to the cart to display as a warning. Otherwise (if the source of the validation is a checkout), then we want any violations to the checkout to display as an error. Line 7: Set the violation description that will be displayed when there is a violation to the toothbrush validation. Lines 9-11: Check the line items in the cart or checkout to see if they contain a toothbrush. We do this by calling a function that we create later in our code to check whether the catalog ID of the toothbrush in the cart or checkout matches the catalog item ID in the list of catalog items. If it matches, get the toothbrush's quantity. Lines 12-20: If the toothbrush's quantity is between 1-200, set the severity, target, and description of the violation and push them into a violations array. The target is set to the line item's default since the validation violation is on a specific line item. Line 21: Set the violation description that will be displayed when there is a violation to the minimum total item quantity validation. Lines 22- 32: Calculate the cart's total quantity. If the quantity is less than 300, set the severity, target, and description of the violation and push them into a violations array. The target is set to the other (general) validation violation default since the validation violation is not on a specific line item, rather on the total item quantity of the cartcheckout. Lines 33- 37: Here we create a function to check whether the ID we pass into the function (the catalog ID of the toothbrush in the cart or checkout) matches the catalog item ID in the list of catalog items.

Optional: Add files to an extension

If you don't want to keep all of your code in the main files, you can add files to the extension's folder and import functions and objects into the main files.

  • Wix Editor:

    1. Hover over the extension folder's name and click Show More .
    2. Select the New.js file.

  • Wix Studio: Create a new file in the extension's folder.

To import from these files to the main files, use the following syntax:

Copy
1
import { functionName } from './myFileName.js';

Optional: Test an extension

You can test your extension before publishing your site in the Wix Editor using functional testing like you would with any backend Velo code. Make sure your getValidationViolations() function's return values are properly formatted.

You can test your extension after deploying for both Wix Editor and Wix Studio. To test your extension after deploying, add console logs to your code. The results appear in the Site Events log.

Step 3: Deploy the extension

Once your code files are ready, publish your site. Navigate to your site, and add an item to your Cart or Checkout. Any violations to the validations you've customized are displayed on the checkout or the cart pages.

  1. Once your code files are ready, click Save. Then Publish your site.
  2. After your custom extensions are published, open your site.
  3. Your custom extension is then deployed, and any validation violations should appear on your site's Checkout and Cart pages.

If a customer adds only 20 Bamboo Toothbrushes to their cart. They will receive the following warnings displayed in their cart.

The validation violation response for the cart will look like this:

Copy
1
{                                                
2
  "violations": [{                                 
3
    "severity": "WARNING",               
4
    "target": {                                                               
5
      "lineItem": {
6
        "_id": "00000000-0000-0000-0000-000000000001"
7
        "name": "LINE_ITEM_DEFAULT"
8
      }                    
9
    },
10
    "description": "You must purchase at least 200 Bamboo Toothbrushes."      
11
  },
12
  {                                 
13
    "severity": "WARNING",               
14
    "target": {                                                               
15
      "other": {
16
        "name": "OTHER_DEFAULT"
17
      }                    
18
    },
19
    "description": "You must purchase a minimum of 300 items."      
20
  }]                                                  
21
 }

If the same customer from above proceeds to the checkout page, they will receive the following errors displayed in their checkout.

The validation violation response for the checkout will look like this:

Copy
1
{                                                
2
  "violations": [{                                 
3
    "severity": "ERROR",               
4
    "target": {                                                               
5
      "lineItem": {
6
        "name": "LINE_ITEM_DEFAULT"
7
      }                    
8
    },
9
    "description": "You must purchase at least 200 Bamboo Toothbrushes."      
10
  },
11
  {                                 
12
    "severity": "ERROR",               
13
    "target": {                                                               
14
      "other": {
15
        "name": "OTHER_DEFAULT"
16
      }                    
17
    },
18
    "description": "You must purchase a minimum of 300 items."      
19
  }           ]                                                  
20
 }

Note:

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 custom extension's configuration file.

Remove an extension

You can remove the extension from your site. Do the following:

Wix Editor:

  1. In the Public & Backend section of the Velo sidebar, under Custom Extensions, hover over the extension's folder and click Show More .
  2. Select Remove.
  3. Click Remove.

Wix Studio: Right click on the extension's folder and select Delete Permanently.

Was this helpful?
Yes
No