Tutorial: Validations Service Plugin

Wix Service Plugins (formerly SPIs and custom extensions) allow you to implement custom logic to change how your site behaves and displays. For example, when you set up a Wix eCommerce site, there are a small number of validations to choose from. The validations service plugin 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.

Read more information on how to implement a service plugin.

With the Validations service plugin 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 plugin on your site using Velo. We created an example to demonstrate how you can use service plugins to validate your checkout and cart pages. We use the example of a wholesale store where a customer must purchase a minimum total of 300 items, and if a customer purchases toothbrushes, then they must purchase at least 200 toothbrushes.

The process has 3 steps:

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

Step 1: Create a new validation plugin

The first step in setting up your new plugin is to add it to your site. This process creates a new folder in the Service Plugins 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 Service Plugins section:

   • Wix Studio: Click Public & Backend.
   • Wix Editor: Scroll down to the Service Plugins panel at the bottom of the sidebar.

4. Next to Service Plugins, click , then click eCommerce Validation. (In Wix Editor you need to hover over Service Plugins.)

5. Follow the prompts to add the plugin 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 service plugin doesn't appear, try refreshing both the Studio Editor and the Wix IDE.

8. Publish your site.

Step 2: Implement the plugin

The procedure in the previous step creates a folder in the service plugins 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 plugin you chose. Inside this is another folder with the name of the plugin you set up. This folder contains 2 files, minimums.js and minimums-config.js. We implement the custom code for our plugin in these files.

minimum-config.js

This file is where write the code for setting up the plugin'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 service plugin 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 service plugin's configuration file.

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 plugin. 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 service plugin 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:

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 the plugin

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

• Wix Editor:

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

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

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

Optional: Test the plugin

You can test your plugin 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 plugin after deploying for both Wix Editor and Wix Studio. To test your plugin after deploying, add console logs to your code. The results appear in Wix Logs.

Step 3: Deploy the plugin

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 service plugins are published, open your site.
3. Your service plugin 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:

If the same customer from above proceeds to the checkout page, they will see the following errors displayed at the top of the checkout page:

And again at the button of the page. The button is disabled until the errors are resolved:

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

Remove the plugin

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

Wix Editor:

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

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