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.

Custom extensions are implemented with Velo SPIs, and they behave just like the extensions Wix already supports. You can manage extended services from your site's dashboard.

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.

Note This feature is still in beta testing and may change significantly before the final release. Elements that are not fully functional are noted below.

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:

Copy
1

Notes

  • Item objects don't include the physical dimensions of the products in your store. You might need to include these to retrieve 3rd-party shipping rates. In this case, store them in a separate collection together with a unique identifier such as an SKU. You can retrieve the dimensions from this collection in your custom extension code using the wix-data API and include them in your 3rd-party API call.
  • The value of shippingOrigin is based on the business address set on your site. To set a business address open your site’s dashboard and go to Settings > Business Info > Location & Contact Info > Address.

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:

Copy
1

Note The currency property of each shippingRate object must match the site's currency. Shipping rates with other currencies are not displayed on the site. Include any currency conversions in your implementation.

<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:

Copy
1

Note Displaying the details provided by getConfig() is not supported in beta testing. For the purposes of testing, use a dummy value for your getConfig() return object, such as the one above.

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

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.

Note: These examples and their steps are based on Wix Editor sites. You can adapt the steps for a Wix Studio site by using the equivalent Wix Studio features.

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.

Copy
1

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.

Note: Clicking the link to the sample site opens a copy of the site. Publishing the copy adds it to your Wix account.

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.

Note: Clicking the link to the sample site opens a copy of the site. Publishing the copy adds it to your Wix account.

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.
Was this helpful?
Yes
No