Velo Tutorial: eCommerce Additional Fees 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 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 emision fee? The answer is Custom Extensions.

Custom extensions are implemented with Velo using Wix SPIs. Learn more about custom extensions. 

With the Additional Fees custom extenstion, 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 extension on your site using Velo.

The process has 3 steps:

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

Step 1: Create a new Additional Fees custom 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 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 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 Additional Fees 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-additional-fees. 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, <my-extension-name>.js and <my-extension-name>-config.js.

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

<my-extension-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 extension. The function contains the following parameter:

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

Example options object:

1
[
2
  {
3
    "lineItems":[
4
      {
5
        "physicalProperties":{
6
          "sku":"0001",
7
          "shippable":true
8
        },
9
        "quantity":1,
10
        "price":"4.00",
11
        "_id":"00000000-0000-0000-0000-000000000004",
12
        "rootCatalogItemId":"cb688748-3f3d-e5f4-accb-5bf894a4ecd0",
13
        "productName":"Luxury glass",
14
        "catalogReference":{
15
          "catalogItemId":"cb688748-3f3d-e5f4-accb-5bf894a4ecd0",
16
          "appId":"1380b703-ce81-ff05-f115-39571d94dfcd",
17
          "options":{
18
            "options":{
19
              
20
            },
21
            "variantId":"00000000-0000-0000-0000-000000000000"
22
          }
23
        }
24
      }
25
    ],
26
    "shippingInfo":{
27
      "selectedCarrierServiceOption":{
28
        "code":"fc538775-9417-87a9-6808-c71996de4723",
29
        "logistics":{
30
          "deliveryTime":"3-5 days",
31
          "instructions":"Deliver during opening hours.",
32
          "pickupDetails":{}
33
        },
34
        "carrierId":"c8a08776-c095-4dec-8553-8f9698d86adc",
35
        "title":"standard shipping",
36
        "requestedShippingOption":"true",
37
      },
38
      "carrierServiceOptions":[
39
        {
40
          "carrierId":"c8a08776-c095-4dec-8553-8f9698d86adc",
41
          "shippingOptions":[
42
            {
43
              "code":"fc538775-9417-87a9-6808-c71996de4723",
44
              "title":"standard shipping",
45
              "logistics":{
46
                "deliveryTime":"3-5 days",
47
                "instructions":"Deliver during opening hours.",
48
                "pickupDetails":{}
49
              }
50
            }
51
          ]
52
        }
53
      ]
54
    }
55
  }
56
]

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 SPI Reference.

Example return value:

1
{
2
  additionalFees: [
3
    {
4
      code: "wrapping-fee",
5
      name: "Wrapping Fee",
6
      price: "5",
7
      taxDetails: {
8
        taxable: false
9
      }
10
    } 
11
  ],
12
  currency: "EUR"
13
}

<my-extension-name>-config.js

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

Example:

1
export function getConfig() {
2
  return {};
3
}

Add files to the 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:

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

Test the extension

You can test your extension 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 extension after deploying for both Wix Editor and Wix Studio. To test your extension after deploying, add console log statements 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. 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 custom extensions 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 Custom Extensions 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 extension

You can remove an extension from your site.

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.