Search.../
  1. SPIs

getShippingRates( )

Retrieves shipping rates provided by a custom shipping rates extension.

Description

This function is automatically called by Wix eCommerce to retrieve the shipping rates provided by your extension. This happens when actions are performed on the cart/checkout entities/pages and/or when there is a change to any property in the options parameter. For example, when an item is added to the cart.

Notes:

  • Every time getShippingRates() is called, the response is cached. This cache is valid for 10 minutes and is used until a change is made to any property in the options parameter, at which point the cache is refreshed.
  • If your extension fails to respond within 10 seconds, the call will purposefully fail to ensure a smooth user experience. We recommend optimizing your logic: calls to external APIs take longer and are outside our control; use fewer wixData actions when possible.

Where to find getShippingRates()

When you add the Shipping Rates custom extension, a folder is automatically added to your site. Use the <my-extension-name>.js file in the folder to write your custom shipping rates code.

For more information on customizing your shipping rate options, see Tutorial: Shipping Rates Custom Extension.

Syntax

function getShippingRates(options: Options): Promise<ShippingRates>

getShippingRates Parameters

NAME
TYPE
DESCRIPTION
options
Options

Shipping origin, shipping destination, and general configurations.

Returns

Fulfilled - Available shipping rates.

Return Type:

Promise<ShippingRates>
NAME
TYPE
DESCRIPTION
shippingRates
Array<ShippingRate>

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

Was this helpful?

Example of a shippingRates return value

Copy Code
1export const getShippingRates = (options) => {
2

3  return {
4    "shippingRates": [{
5      "code": "usps-international",
6      "title": "USPS - International",
7      "logistics": {
8        "deliveryTime": "2-5 days"
9      },
10      "cost": {
11        "price": "15",
12        "currency": "USD",
13        "additionalCharges": [{
14          "price": "10",
15          "type": "HANDLING_FEE",
16          "details": "Handling fee of $5 applied for fragile items."
17        }]
18      }
19    }]
20  };
21};
Return shipping rates based on quantity of items in a cart

Copy Code
1export const getShippingRates = (options) => {
2  return getShippingRatesByQuantity(options)
3}
4

5// Tally the quantity of all items
6function calculateTotalCartQuantity(lineItems) {
7  return lineItems.reduce((acc, lineItem) => acc += lineItem.quantity, 0);
8}
9

10// Return shipping rates based on the calculated items' quantity
11function getShippingRatesByQuantity(options) {
12  const cartQuantity = calculateTotalCartQuantity(options.lineItems);
13

14  if (cartQuantity >= 3) {
15    return {
16      shippingRates: [{
17        code: 'quantity_more_3',
18        title: 'Quantity > 3',
19        logistics: {
20          deliveryTime: '3-5 Days'
21        },
22        cost: {
23          price: '10.00',
24          // Currency value is taken from provided options object
25          currency: "USD"
26        }
27      }]
28    };
29  };
30

31  // If cartQuantity is less than 3, the following shipping rate is returned
32  return {
33    shippingRates: [{
34      code: 'quantity_more_1',
35      title: '1 Item',
36      logistics: {
37        deliveryTime: '3-5 Days'
38      },
39      cost: {
40        price: '20.00',
41        currency: "USD"
42      }
43    }]
44  };
45};