Velo Tutorial: eCommerce Additional Fees 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 limitations to how you can charge buyers of your products. What if you want to charge buyers an extra fee for gift-wrapping an item? What if you want to charge a carbon emission fee? The answer is service plugins.

Read more information on how to implement a service plugin.

With the Additional Fees service plugin, you can define the additional fees that fit your site's needs. You can also customize code to calculate different types of additional fees. 

For example, you can add some of the following additional fees to your checkout flow: 

• Gift wrapping fees
• Shipping insurance fees
• Item warranty fees
• Credit card service fees
• Shipping and handling fees
• Fragile packaging fees
• Carbon offset fees

These additional fees are displayed in your store's Cart and Checkout pages. 

This article explains how to set up an Additional Fees plugin on your site using Velo.

The process has 3 steps:

1. Create a new Additional Fees service plugin on your site.
2. Implement your plugin with custom code.
3. Deploy the plugin.

Step 1: Create a new Additional Fees service 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 Code 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 or the Wix Bookings 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 Code sidebar.

3. Go to the Service Plugins section:

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

4. Hover over Service Plugins and click , then click Additional Fees.

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-additional-fees. 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 Code 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, <my-plugin-name>.js and <my-plugin-name>-config.js.

Implement the custom code for your plugin in these files. Below are some guidelines for writing your code. 

<my-plugin-name>.js

The code in this file defines a function called calculateAdditionalFees(). This function is called by Wix eCommerce when an action occurs in the cart or on the checkout page, and then receives the additional fees provided by your plugin. The function contains the following parameter:

• options: An object containing data and shipping information about the items in your cart. Your plugin can use this data to calculate any additional fees. For more details, see the Additional Fees Service Plugin Reference. 

Example options object:

The calculateAdditionalFees() function returns an object containing an array called additionalFees and a property called currency, defining the additional fees and currency that appears in the Cart and on the Checkout pages. For more details, see the Additional Fees Service Plugin Reference.

Example return value:

<my-plugin-name>-config.js

The code in this file defines a function named getConfig() that returns an empty object.

Example:

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:

Test the plugin

You can test your plugin before publishing your site in the Wix Editor using functional testing like you would any backend Velo code. Make sure your calculateAdditionalFees() 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 log statements 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. Any addtional fees you've customized are displayed in the cart and on the checkout pages. if they pertain to your cart items. 

1. Once your code files are ready, click Save. 

2. Publish your site. 

3. After your service plugins are published, open your site.

4. Navigate to your Cart or Checkout page, and make a change. For example, add an item to your cart, or select a shipping location.

5. See your custom additional fees appear in your site's Cart and in your site's Checkout pages. 

   

Example

We created an example to demonstrate how you can use the service plugins feature to extend the additional fees on your site. 

Wrapping Fee

In this example, a wrapping fee has been integrated into a store's site. The code in the additional-fees.js file counts all the items in the cart that contain the words glass, bowls, vase, or plates in their names. These items are considered fragile. The wrapping fee for each fragile item in a customer's cart is then calculated. If a cart contains at least 5 fragile items, the wrapping fee is not applied.

We built a sample site where you can see this code in action. To set up a working copy of the sample site, do the following:

1. Open a copy of the sample site.
2. Publish the site to save the copy to your Wix account.
3. In your new site's dashboard, go to Settings.
4. Click Language & Region.
5. Scroll down to Site Currency.
6. Click the Currency drop-down menu and select US Dollar - USD ($).
7. Click Save.

Remove an plugin

You can remove an plugin from your site.

Wix Editor:

1. In the Public & Backend section of the Code 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.