Introduction

The Shipping Rates service plugin (formerly SPI) provides functionality for connecting your site to shipping rates providers not currently supported by Wix. You can also implement custom or external shipping rate options that don't come natively with Wix in your eCommerce purchase flows. These rates are displayed on your store's cart and checkout pages. For example, you're not limited to how Wix apps, such as Wix Stores and Wix Bookings, define the number of shipping providers to choose from.

Wix eCommerce calls the service plugin endpoint getShippingRates() to retrieve the relevant shipping rates.

Learn more:

To add a service plugin

  1. Add the plugin to your site.
  2. Update the getConfig() function in the -config.js file that is added to your site during step 1.
  3. Update the getShippingRates() function in the .js file that is added to your site during step 1.
Did this help?

getConfig( )


Retrieves the configuration of your shipping rates plugin.

Set your shipping rates configuration in the return of the getConfig() function. Wix calls this function when you publish your site. Changes to the configuration don't take effect until you publish your site.

The object returned by getConfig() contains values used to display the extended shipping rate on your site's dashboard.

Where to find getConfig()

When you add the Shipping Rates service plugin, a folder is automatically added to your site. Use the -config.js file in the folder to set the default configuration for your implementation of the service plugin.

For more information on setting your configuration, see Tutorial: Shipping Rates Service Plugin.

Method Declaration
Copy
function getConfig(): Promise<ShippingRatesConfigResponse>;
Request
This method does not take any parameters
Returns
Return Type:Promise<ShippingRatesConfigResponse>
Example of a configuration file
JavaScript
// Place this code in the <my-extension-name>-config.js file // in the 'ecom-shipping-rates' folder of the // Custom Extensions section on your site. export function getConfig() { return { name: "East-Coast Shipping Provider", description: "Providing shipping options for the US east-coast", }; }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getShippingRates( )


Retrieves shipping rates provided by a custom shipping rates plugin.

This function is automatically called by Wix eCommerce to retrieve the shipping rates provided by your plugin. 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 plugin 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 service plugin, a folder is automatically added to your site. Use the .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 Service Plugin.

Method Declaration
Copy
function getShippingRates(
  options: Options,
  context: Context,
): Promise<ShippingRates>;
Method Parameters
optionsOptionsRequired

Shipping origin, shipping destination, and general configurations.


contextContextRequired

Metadata about the request.

Returns
Return Type:Promise<ShippingRates>
JavaScript
export const getShippingRates = (options) => { return { shippingRates: [ { code: "usps-international", title: "USPS - International", logistics: { deliveryTime: "2-5 days", }, cost: { price: "15", currency: "USD", additionalCharges: [ { price: "10", type: "HANDLING_FEE", details: "Handling fee of $5 applied for fragile items.", }, ], }, }, ], }; };
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?