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

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/shipping-rates/shipping-rates-integration-service-plugin/introduction.md

## Article Content:

# About the Wix eCommerce Shipping Rates Service Plugin

<blockquote class="important">

__Important:__ 
When developing websites or building apps with Blocks, use [Velo service plugins](https://dev.wix.com/docs/velo/events-service-plugins/about-events-service-plugins-and-the-sdk.md).

</blockquote>

As a shipping provider, you can integrate with Wix to allow a merchant's stores or businesses to request and use your shipping services on their Wix sites.
Your shipping rates are then displayed on the site's cart and checkout pages.

The integration is done via an app in the Wix App Market and by implementing the Shipping Rates [service plugin](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md). After the app is installed on a site, Wix triggers a call to your service whenever the site needs to retrieve shipping rates for a transaction.

Using the service plugin, you can design your app to:
+ Provide shipping estimates, including fees and times.
+ Provide shipping rates using your own custom logic.
+ Provide services for delivery and pickup.

::::tabs
:::REST_TAB

## Prerequisites

Complete the following steps to adapt Wix system's integration to make your shipping rates available to merchants and their customers.

1. Create an [app](https://dev.wix.com/dc3/my-apps/) in your Wix Studio workspace and retrieve its app ID either from the URL or as displayed in your app's dashboard.

    ![Sample App ID](https://wixmp-833713b177cebf373f611808.wixmp.com/images/7bdf57337e20b2aa283291e35177e08b.png "Sample App ID")

1. Go to [Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions.md) in your app's dashboard.
1. Click **Create Extension** in the top right.
1. Filter by **eCommerce** in the left menu, then find **Ecom Shipping Rates** and click **Create**.
1. Use the JSON editor to create the extension's configuration file. Take care to include the required fields noted in the table below. Click **Save**.

    | Name                 | Type                     | Description       |
    | ---------------------|--------------------------|-------------------|
    | `deploymentUri`      | string                   | Required. Base URI where the endpoints are called. Wix eCommerce appends the endpoint path to the base URI. For example, to call the Get Shipping Rates endpoint at `https://my-shipping-provider.com/v1/getRates`, the base URI you provide here is `https://my-shipping-provider.com/`.|
    | `name`               | string                   | Required. Human-readable name of the shipping provider. Max characters: 64.|
    | `description`        | string                   | Description of the shipping provider. Max characters: 200.|
    | `learnMoreUrl`       | string                   | URL to more info about the shipping provider.|
    | `dashboardUrl`       | string                   | URL to reach the shipping provider app's dashboard.|
    | `fallbackDefinitionMandatory`      | boolean    | Whether to require the site owner to define a fallback/default rate. Set to `true` if you do not provide rates as part of the integration.|
    | `thumbnail_url`      | string                   | Thumbnail image of the shipping rates provider. Displayed in the shipping settings section in the Dashboard. The URL must be of an image uploaded to the [Wix Media Manager](https://support.wix.com/en/article/wix-media-uploading-media-to-the-media-manager).|

1. Click [**Test Your App**](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/test-your-app/test-your-app-on-a-premium-site.md).
1. After adding your app to the test site, [enable a shipping rule in the dashboard](https://support.wix.com/en/article/wix-stores-offering-real-time-shipping-rates-via-third-party-apps) to show your shipping rates during checkout.

:::
:::SDK_TAB

## Get started

Follow these steps to begin implementing your service plugin.

### Step 1 | Choose a framework

You can implement this service plugin with the following [frameworks](https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks.md):

+ **Wix CLI:** Learn how to [implement a service plugin with the CLI and the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md).
+ **Self-hosted:** Learn how to [implement a self-hosted service plugin with the SDK and the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md).

### Step 2 | Configure your service plugin

To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can [configure your plugin in the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md#step-1--add-a-service-plugin-extension-to-your-app). For details, see [Shipping Rates Extension Configuration](https://dev.wix.com/docs/rest/business-solutions/e-commerce/extensions/shipping-rates/shipping-rates-integration-service-plugin/extension-config.md).

### Step 3 | Define handler functions

Use [`shippingRates.provideHandlers()`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md#step-4--define-handler-functions) to define the following handler functions that implement your custom business logic. Make sure you define all required functions.

| Function                    | Required       |
|-----------------------------|----------------|
| [`getShippingRates()`](https://dev.wix.com/docs/rest/business-solutions/e-commerce/extensions/shipping-rates/shipping-rates-integration-service-plugin/get-shipping-rates.md)    | Yes            |

## Code examples

Below is an example for implementing the Shipping Rates service plugin in your code.

### CLI: Basic code structure.

This is the basic code structure for implementing the Shipping Rates service plugin with the Wix CLI:

```js
import { shippingRates } from '@wix/ecom/service-plugins'

shippingRates.provideHandlers({
  getShippingRates: async (payload) => {

    const {request, metadata} = payload;

    // Add your logic here

  }
});
  
```

### Self-hosted: Basic code structure

This is the basic code structure for implementing a self-hosted Shipping Rates service plugin:

```js
import { createClient } from '@wix/sdk';
import { shippingRates } from '@wix/ecom/service-plugins'

const wixClient = createClient({
  auth: {
    appId: <YOUR_APP_ID>,
    publicKey: <YOUR_APP_PUBLIC_KEY>
  },
  modules: { shippingRates }
});

wixClient.shippingRates.provideHandlers({
  getShippingRates: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  }
});

// Implement a router to process all requests
express.post('/plugins-and-webhooks/*', (req, res) => {
  wixClient.process(req);
});
  
```

:::
::::

## See also

+ [Tutorial | Create a Self-hosted Custom Shipping Rates App](https://dev.wix.com/docs/build-apps/get-started/tutorials/tutorial-create-a-self-hosted-custom-shipping-rates-app.md)
+ [About Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md)
+ [Add a Service Plugin Extension With the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md)
+ [Add a Self-hosted Service Plugin With the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md)
+ [Add Self-hosted Service Plugin Extensions with REST](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest.md)