Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

GenericShippingRatesWixError

if (!request.postalCode) {
                   throw new MissingPostalCodeError({
                      supportedPostalCodes: ['12345', '54321'],
                   });
                }
                    

dummy example title

InvalidAddressWixError

InvalidPostalCodeWixError

MissingPostalCodeWixError

payload

GetShippingRatesEnvelope

This method retrieves applicable shipping rates for a delivery from your app.

Wix calls this method when certain actions are performed on the cart and/or checkout. For example, when an item is added to the cart, or the shipping destination is changed.

getShippingRates

GetShippingRatesResponse

# About the Shipping Rates Service Plugin

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). 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.

## Get started

Follow these steps to begin implementing your service plugin.

### Choose a framework

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


+ **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).

### 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#step-1--add-a-service-plugin-extension-to-your-app). 

### 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#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/sdk/backend-modules/ecom/service-plugins/shipping-rates/get-shipping-rates)    | Yes            |

## Code examples

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


### 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: GetShippingRatesEnvelope) => {

    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

+ [About Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions)

+ [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)
+ [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)

ecom_shipping-rates

AdditionalCharge

Details of the additional charge. For example, `"Handling fee of $5 applied for gift wrapping"`.

details

string

Cost of additional charge. For example, `12.5`.

price

type

Address

Main address line, usually street and number as free text.

addressLine

streetAddress

addressLine1

Free text providing more detailed address info. Usually contains Apt, Suite, and Floor.

addressLine2

city

country

postalCode

Subdivision shorthand. Usually, a short code (2 or 3 letters) that represents a state, region, prefecture, or province. e.g. NY

subdivision

ApplicationError

code

data

description

CatalogReference

ID of the app providing the catalog.

You can get your app's ID from its page in the [Wix Dev Center](https://dev.wix.com/apps).

For items from Wix catalogs, the following values always apply:
+ Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"`
+ Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"`
+ Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"`

appId

ID of the item within the catalog it belongs to.

catalogItemId

Additional item details in key:value pairs. Use this optional field to provide more specificity with item selection. The `options` field values differ depending on which catalog is providing the items.

For products and variants from a Wix Stores catalog, learn more about [eCommerce integration](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/e-commerce-integration).

options

Context

3 capital letters string representing a currency according to ISO-4217

currency

The identification type and identity data

identity

IdentificationData

instanceId

A string representing a language and region in the format of "xx-XX". First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2

languages

A unique identifier for each request. Can be used for logging / troubleshooting

requestId

DeliveryLogistics

When the item is expected to be delivered in free text. For example, `"3-5 business days"`.

deliveryTime

Instructions for delivery. For example, for pickup: `"Ensure to come during business hours, and please don't park in the disabled spot"`.

instructions

Pickup details. Should be returned only if order is for pickup.

pickupDetails

PickupDetails

DeliveryPreferences

preferredCode

FieldViolation

field

ruleName

violatedRule

RuleType

FullAddressContactDetails

company

email

firstName

lastName

phone

Tax info. Currently usable only in Brazil.

vatId

VatId

GenericShippingRatesError

errors

metadata

request

GetShippingRatesRequest

buyerContactDetails

List of delivery preferences, for example preferred delivery code (`shippingOptionId`).

deliveryPreferences

lineItems

Persistent ID that correlates between the various eCommerce elements: cart, checkout, and order.

purchaseFlowId

shippingDestination

Address item is shipped from. This is the site owner's business address.

shippingOrigin

Whether tax is included in the items' prices.

taxIncludedInPrices

boolean

Weight measurement unit used for all items in the shipment.

Supported values:
+ `"KG"`: kilograms
+ `"LB"`: pounds

weightUnit

WeightUnit

Available shipping rates. These define the shipping rate options that are displayed to site visitors on the cart and checkout pages.

shippingRates

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

identityType

IdentityType

InvalidAddressError

fields

InvalidPostalCodeError

error

MissingPostalCodeError

PhysicalProperties

shippable

Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku).

Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request.

weight

number

address

Pickup method.

Supported values:
+ `"STORE_PICKUP"`: When pickup is from the merchant's brick and mortar store.
+ `"PICKUP_POINT"`: When item is shipped to a specified pickup point.

pickupMethod

PickupMethod

ProductItem

catalogReference

item delivery destination index in the shipping addresses list

deliveryDestinationIndex

where the item is delivered from index in the from addresses list

deliveryOriginIndex

name

physicalProperties

priceBeforeDiscount

quantity

whether tax is included in line item price

taxIncludedInPrice

Total line item price after discounts. This is equal to `price` multiplied by `quantity`.

totalPrice

totalPriceBeforeDiscount

ShippingOption

Unique code that acts as an ID for a shipping rate. For example, `"usps_std_overnight"`.

cost

ShippingPrice

logistics

Shipping rate title. For example, `"USPS Standard Overnight Delivery"`, `"Standard"`, or `"First-Class Package International"`.

title

Additional costs. For example, a handling fee for packaging fragile items.

additionalCharges

Currency of the shipping rate price as a 3-letter [ISO-4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). Must align with the `currency` passed to the function under the `metadata` field.

The shipping rate's price. Must align with the [currency's decimal separator](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).

StreetAddress

Tax type.

Supported values:
+ `CPF`: for individual tax payers
+ `CNPJ`: for corporations

getShippingRates( )