Velo Tutorial: eCommerce Shipping Rates Service Plugin

Wix service plugins (formerly SPIs and 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.

Read more information on how to implement a service plugin.

With a Shipping Rates service plugin, 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 plugin on your site using Velo.

The process has 3 steps:

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

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 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 to your site.

  2. Enable coding:

    • Wix Studio: If necessary, click Code icon 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 Shipping Rates.

  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-shipping-rates. 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.

Here are some guidelines for writing your code:

<my-plugin-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 plugin. 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 service plugin reference.

Examples options object:

Copy

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

Example return value:

Copy

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

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

Copy

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 getShippingRates 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, you need to deploy your plugin 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 plugin.

    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 service plugin is deployed, your custom shipping rates appear on your site's Cart and Checkout pages.

Examples

Service plugins 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 service plugins 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

Display rates based on product and cart data

In this example, product weight and quantity data is used to determine shipping rates. The plugin 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 plugin'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 plugin

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.
Did this help?