Velo Tutorial: eCommerce Shipping Rates Custom Extension

Wix custom extensions allow you to expand what your site can do by integrating with 3rd-party services not currently supported by Wix. They also allow you to implement custom logic to change how your site displays and behaves using Velo. Learn more about using Custom App Extensions Using SPIs.

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.

With a Shipping Rates custom extension, you can connect your site to shipping rates providers not currently supported by Wix. You can also implement custom shipping rates and options using code. These rates are displayed on your store's Cart and Checkout pages. 

This guide explains how to set up a shipping rates extension on your site using Velo.

The process has 3 steps:

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

Step 1: Create a new shipping rates 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 Shipping Rates 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-shipping-rates. 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.

Here are some guidelines for writing your code:

<my-extension-name>.js

The code in this file defines a function named getShippingRates(). This function is called by Wix eCommerce to retrieve the shipping rates provided by your extension. The function accepts the following parameter:

options: An object containing data about line items, the shipping destination, the shipping origin, and general configurations. For more details, see the SPI Reference.

Examples options object:

1
{
2
  "lineItems": [
3
    {
4
      "name": "toy plane",
5
      "quantity": 1,
6
      "catalogReference": {
7
        "appId": "1380b703-ce81-ff05-f115-39571d94dfcd",
8
        "catalogItemId": "1a2d7e83-4bef-31d5-09e1-3326ee271c09"
9
      },
10
      "physicalProperties": {
11
        "sku": "0002",
12
        "shippable": true,
13
        "weight": 1
14
      },
15
      "price": "200",
16
      "priceBeforeDiscount": "250",
17
     "totalPrice": "200",
18
     "totalPriceBeforeDiscount": "250"
19
    }
20
  ],
21
  "shippingDestination": {
22
    "addressLine1": "34 Elizabeth Street",
23
    "addressLine2": "4th floor",
24
    "city": "Melbourne",
25
    "country": "AU",
26
    "postalCode": "3000",
27
    "subdivision": "VIC"
28
  },
29
  "shippingOrigin": {
30
    "addressLine1": "235 West 23rd Street",
31
    "addressLine2": "3rd floor",
32
    "city": "New York",
33
    "country": "US",
34
    "postalCode": "10011",
35
    "subdivision": "US-NY"
36
  },
37
  "buyerDetails": {},
38
  "weightUnit": "KG"
39
}

The getShippingRates() function must return an object with a key called shippingRates. The value of this key is an array of shippingRate objects. These objects define the shipping rate options that site visitors see on the Cart and Checkout pages. For more details, see the SPI Reference.

Example return value:

1
{                                                
2
  "shippingRates": [{                                 
3
    "code": "123456-abcdef", // A unique identifier               
4
    "title": "USPS - International",    
5
    "cost": {                                       
6
      "price": "15",                              
7
      "currency": "EUR",                          
8
      "additionalCharges": [{
9
        "price": "12",
10
        "details": "Shipping surcharges and handling fees"
11
        }]                     
12
    },
13
    "logistics": {
14
      "deliveryTime": "2-5 days",
15
      "instructions": "Please be available"
16
    }                                               
17
  }]                                                  
18
 }

<my-extension-name>-config.js

The code in this file defines a function named getConfig() that returns an object containing the values used to display the extended shipping rate on your site's dashboard.

Example return object:

1
{
2
  "name": "best_shipping_rates_provider"
3
  "description": "Shipping rates for the US east-coast"
4
}

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:

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

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 getShippingRates 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, you need to deploy your extension and enable it on your site's dashboard.

1. Publish your site.

   Note: There may be a delay between publishing the site and the new shipping rates options appearing on your site's dashboard.

2. Go to the Shipping & Fulfillment settings on your site's dashboard.

3. Click the region where you want to apply the new shipping rates.

4. Under Installed Apps click the toggle for your new shipping rates extension.

   Note: The names of the shipping rates options don't appear in the beta version. The different options available are listed based on the order in which you add them to your site.

5. Click Save.  

6. Once your custom extension is deployed, your custom shipping rates appear on your site's Cart and Checkout pages.

   

Examples

Custom extensions allow you to implement shipping rates with custom logic and display them on your site. We created some examples to demonstrate how you can use custom extensions to extend the shipping rates options on your site.

Display rates by expected delivery

In this example, shipping options for a variety of shipping times are displayed. To test this code, paste it into your .js file.

1
export const getShippingRates = async (options) => {
2
  return {
3
    ‘shippingRates’: [{
4
      title: 'Same day delivery',
5
      code: 'one_day_rush',
6
      logistics: {
7
        deliveryTime: 'Today',
8
        instructions: 'Please be available',
9
      },
10
      cost: {
11
        price: "20.00",
12
        currency: 'EUR',
13
        additionalCharges: [],
14
      }
15
    }, 
16
    {
17
      title: 'Next Day',
18
      code: 'next-day',
19
      logistics: {
20
        deliveryTime: 'Tomorrow',
21
        instructions: 'Please be available',
22
      },
23
      cost: {
24
        price: '15.00',
25
        currency: 'EUR',
26
        additionalCharges: [],
27
      }
28
    }, 
29
    {
30
      title: '2 Days',
31
      code: 'two_days',
32
      logistics: {
33
        deliveryTime: '2 Days',
34
        instructions: 'Please be available',
35
      },
36
      cost: {
37
        price: '12.00',
38
        currency: 'EUR',
39
        additionalCharges: [],
40
      }
41
    }]
42
  }
43
};

Display rates based on product and cart data

In this example, product weight and quantity data is used to determine shipping rates. The extension includes 2 helper files. One, rates-by-weight, includes code that calculates a shipping rate based on the total weight of the shipment. The second file, rates-by-quantity, calculates a shipping rate based on the total number of items being shipped. Both the weight and quantity values are calculated using the product data that’s passed into the extension's getShippingRates function. The code in the example’s getShippingRates function calculates the rates for shipping by weight or by quantity and returns the lower of the two.

We built a sample site where you can see this code in action.

3rd-party extension

We built a sample site that demonstrates 3rd-party integrations. This site integrates with shipping rates provider Easyship and displays the provided rates on the site.

To get the example working you need to get an easyship API key, store the key in a secret on your copy of the sample site, and add a business address to the site:

Step 1: Retrieve and save an easyship API key

1. Publish a copy of the template site to save it to your Wix account.

2. Sign up for a free easyship account.

3. On your account dashboard click Create an Api.

   

4. Enter a name for your API integration and click Connect.

5. Copy the production API key.

   

6. Open your site’s Secrets Manager and create a new secret named `easy-ship-api-token` with your easyship API key as the value.

Step 2: Add a business address to your site

1. On your site’s dashboard, go to Settings > Business Info > Location & Contact Info > Address.
2. Add a business address for the site.
3. Click Save.