> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: eCommerce Shipping Rates Service Plugin

## Article: eCommerce Shipping Rates Custom Extension

## Article Link: https://dev.wix.com/docs/develop-websites/articles/code-tutorials/wix-e-commerce-stores/e-commerce-shipping-rates-service-plugin.md

## Article Content:

# 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](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/integrations/service-plugins-formerly-spis/custom-app-extensions-using-spis.md).

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](https://support.wix.com/en/article/wix-stores-adding-wix-stores) to your site.
2. Enable coding:
    + **Wix Studio:** If necessary, click ![Code icon](https://github.com/wix-incubator/wix-code-docs/assets/50321691/2c41d3df-930f-4e0f-966f-038742adceed) and then **Start Coding**.  
    + **Wix Editor:** Enable [Velo Dev Mode](https://support.wix.com/en/article/about-velo-by-wix#to-enable-velo-on-your-site), and then click the **Public & Backend**  ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/76096845-8b12-44f1-91f6-3dc2e838fdd9/2022/08/29/23d50509-633d-4616-9f56-65add8fa6d0b/d910e041-d150-4f35-aa75-30ad262abc7a.png)  tab in the Code sidebar.
3. Go to the Service Plugins section: 
    + **Wix Studio:** Click **Public & Backend**. 
    + **Wix Editor:** Scroll down to the Service Plugins panel at the bottom of the sidebar.
4.  Hover over **Service Plugins** and click  ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/11fda387-da5a-430a-ada3-46def885b67f/2022/03/02/65d645bd-dee9-40dc-9f91-c44b06d72492/289e91de-47c5-429c-b61d-67bd8d4fd1ec.png) , 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](https://www.wix.com/velo/reference/spis/wix-ecom/ecom-shipping-rates).

Examples options object:

```json
{
  "lineItems": [
    {
      "name": "toy plane",
      "quantity": 1,
      "catalogReference": {
        "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
        "catalogItemId": "1a2d7e83-4bef-31d5-09e1-3326ee271c09"
      },
      "physicalProperties": {
        "sku": "0002",
        "shippable": true,
        "weight": 1
      },
      "price": "200",
      "priceBeforeDiscount": "250",
     "totalPrice": "200",
     "totalPriceBeforeDiscount": "250"
    }
  ],
  "shippingDestination": {
    "addressLine1": "34 Elizabeth Street",
    "addressLine2": "4th floor",
    "city": "Melbourne",
    "country": "AU",
    "postalCode": "3000",
    "subdivision": "VIC"
  },
  "shippingOrigin": {
    "addressLine1": "235 West 23rd Street",
    "addressLine2": "3rd floor",
    "city": "New York",
    "country": "US",
    "postalCode": "10011",
    "subdivision": "US-NY"
  },
  "buyerDetails": {},
  "weightUnit": "KG"
}
```

>**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](https://www.wix.com/velo/reference/wix-data) 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](https://www.wix.com/my-account/site-selector/?buttonText=Go%20to%20Dashboard&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https://www.wix.com/dashboard/{{metaSiteId}}/home/) 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](https://www.wix.com/velo/reference/spis/wix-ecom/ecom-shipping-rates).

Example return value:

```json
{                                                
  "shippingRates": [{                                 
    "code": "123456-abcdef", // A unique identifier               
    "title": "USPS - International",    
    "cost": {                                       
      "price": "15",                              
      "currency": "EUR",                          
      "additionalCharges": [{
        "price": "12",
        "details": "Shipping surcharges and handling fees"
        }]                     
    },
    "logistics": {
      "deliveryTime": "2-5 days",
      "instructions": "Please be available"
    }                                               
  }]                                                  
 }
```

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

```json
{
  "name": "best_shipping_rates_provider"
  "description": "Shipping rates for the US east-coast"
}
```

>**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**  ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/76096845-8b12-44f1-91f6-3dc2e838fdd9/2022/09/04/45269098-373f-4d2c-8168-2fc5242c6024/c890c6a3-6762-4501-bdb4-e44c678108df.png) .
  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:

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

### Test the plugin

You can test your plugin before publishing your site in the Wix Editor using [functional testing](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/testing-monitoring/functional-testing/test-backend-functions-with-functional-testing.md) 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](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/developer-tools/logs/about-logs.md).

## 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](https://www.wix.com/my-account/site-selector/?buttonText=Manage%20Shipping&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https://www.wix.com/dashboard/%7B%7BmetaSiteId%7D%7D/store/shipping-and-tax/list?referralInfo=sidebar) 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.  ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/11fda387-da5a-430a-ada3-46def885b67f/2022/04/14/a46bda1b-a8b2-47f4-8de0-499e862f9c10/517b4381-0385-4d7c-9de7-73ee3a72c817.png)

    > **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.
    
     ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/11fda387-da5a-430a-ada3-46def885b67f/2022/03/02/6594569d-aead-47ff-beb5-eb7e9076fe0c/1b7d35f4-fb86-4b3b-8761-730d5cc7fc82.png) 

## 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](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/velo-workspace/workspaces/wix-studio-working-with-the-code-panel.md).

### 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 **<my-plugin-name>.js** file.

```javascript
export const getShippingRates = async (options) => {
  return {
    shippingRates: [{
      title: 'Same day delivery',
      code: 'one_day_rush',
      logistics: {
        deliveryTime: 'Today',
        instructions: 'Please be available',
      },
      cost: {
        price: "20.00",
        currency: 'EUR',
        additionalCharges: [],
      }
    }, 
    {
      title: 'Next Day',
      code: 'next-day',
      logistics: {
        deliveryTime: 'Tomorrow',
        instructions: 'Please be available',
      },
      cost: {
        price: '15.00',
        currency: 'EUR',
        additionalCharges: [],
      }
    }, 
    {
      title: '2 Days',
      code: 'two_days',
      logistics: {
        deliveryTime: '2 Days',
        instructions: 'Please be available',
      },
      cost: {
        price: '12.00',
        currency: 'EUR',
        additionalCharges: [],
      }
    }]
  }
};
```

### 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](https://manage.wix.com/edit-template/from?originTemplateId=dec2dc1f-740e-42a3-bf1e-625c2df3c4f1&templateId=f17e3efd-2877-47c2-b202-3c9f2641ba14&autoDevMode=true) 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](https://manage.wix.com/edit-template/from?originTemplateId=103d0e2e-46f3-42ec-928c-f61a328495c3&templateId=9e9f7487-d7a5-4548-b4a4-65fedbf08199&autoDevMode=true) that demonstrates 3rd-party integrations. This site integrates with shipping rates provider [Easyship](http://www.easyship.com) 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](http://www.easyship.com/) account.
3.  On your account dashboard click **Create an Api**.

    ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/11fda387-da5a-430a-ada3-46def885b67f/2022/03/02/2723858b-0fe5-48d2-b16a-52069273d078/1f878ea7-5319-4ea7-a0c4-5ac42ccf4c5e.png) 

4.  Enter a name for your API integration and click **Connect**.
5.  Copy the production API key.
    
     ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/11fda387-da5a-430a-ada3-46def885b67f/2022/03/02/f556c4a1-3a8c-4652-89c3-4febf0c23ca1/2fc42273-179d-479f-b817-a2d0cd514a40.png) 
6.  Open your site’s [**Secrets Manager**](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/developer-tools/secrets-manager/about-the-secrets-manager.md) 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**.