About the Wix eCommerce Shipping Rates SPI

As a shipping provider, you can integrate your shipping rates service with Wix to allow a merchant's stores or businesses to request and use your shipping services on their Wix sites. The 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 (created in the Wix Developers Center) and the Wix Shipping Rates SPI.

Using the SPI, 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.

Learn more about implementing an SPI with Wix.

Terminology

  • Get Shipping Rates: Wix calls this SPI endpoint to retrieve the shipping rates you provide.
  • Merchant: Business that offers products on their Wix site to customers.
  • Wix site owner: The person managing the merchant's Wix site.
  • Shipping Rates Provider: A 3rd-party app that implements custom logic to calculate shipping rates.

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 and retrieve its app ID either from the URL or as displayed in the My Apps dashboard in the Wix Developers Center.

    Sample App ID

  2. Go to the Extensions tab in the Wix Developers Center.

  3. Click Create Extension in the top right.

  4. Filter by eCommerce in the left menu, then find Ecom Shipping Rates and click Create.

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

    NameTypeDescription
    deploymentUristringRequired. 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/.
    namestringRequired. Human-readable name of the shipping provider. Max characters: 64.
    descriptionstringDescription of the shipping provider. Max characters: 200.
    learnMoreUrlstringURL to more info about the shipping provider.
    dashboardUrlstringURL to reach the shipping provider app's dashboard.
    fallbackDefinitionMandatorybooleanWhether 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_urlstringThumbnail 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.
  6. Click Test Your App.

  7. After adding your app to the test site, enable a shipping rule in the dashboard to show your shipping rates during checkout.

Was this helpful?
Yes
No

Sample Flow

This article presents a sample flow your app can support. You aren't limited to this exact flow, but it can be a helpful jumping off point as you plan your Shipping Rates integration.

Configuration flow

  1. A site owner installs and authorizes your 3rd-party app to provide shipping rates based on various factors (region, product weight, taxes, and so on). The app collects the JSON Web Token (JWT), decodes it, and stores the resulting instance ID.

    For example, the token in this request:

    Copy
    1
    $ curl -X POST https://ext-server.com/wix-spi/account-ids
    2
    -H 'Content-Type: plain/text'
    3
    -d 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnN0YW5jZUlkIjoiMDQ0NjY3ZjQtYzEzZi00NmMyLTg1MDYtZGU5ZTQyMjkzODk2In0.fxedHrnHUFi6V-S5OH8gL-pY4STxFWZHjj-xo9QUwQY'

    Decodes into:

    Copy
    1
    { "instanceId": "044667f4-c13f-46c2-8506-de9e42293896" }

Display custom shipping rates for eCommerce orders

  1. A customer logs on to the merchant’s Wix site and starts adds a product to the cart or checkout.

  2. Wix sends a Get Shipping Rates SPI request to your app. The payload will include some or all of the fields described in the Body Params and example sections of the Get Shipping Rates reference.

  3. Your Shipping Rates integration triggers the required flow on its platform and processes the request.

    Wix expects an object containing the shipping rates, and either a 4xx HTTP status code (and some errors) or a 200 HTTP status code.

    Example of a successful response from your app:

    Copy
    1
    {
    2
    "shippingRates": [
    3
    {
    4
    "code": "usps_international",
    5
    "title": "USPS - International",
    6
    "logistics": {
    7
    "deliveryTime": "2-5 days"
    8
    },
    9
    "cost": {
    10
    "price": "15",
    11
    "currency": "USD",
    12
    "additionalCharges": [
    13
    {
    14
    "price": "10",
    15
    "type": "HANDLING_FEE",
    16
    "details": "Handling fee of $5 applied for fragile items."
    17
    }
    18
    ]
    19
    }
    20
    }
    21
    ]
    22
    }

    Example of an error:

    Copy
    1
    {
    2
    "errors": [
    3
    {
    4
    "code": "MISSING_POSTAL_CODE",
    5
    "message": "Postal Code was missing from request"
    6
    }
    7
    ]
    8
    }
  4. The Wix site displays the shipping rate/s on the cart or checkout page (depending on where the customer is selecting the shipping option). The customer can confirm the shipping rate before proceeding to payment.

Was this helpful?
Yes
No

PostGet Shipping Rates

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

Wix calls this endpoint 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.

You cannot try out this endpoint because it has to be implemented by an app and can have an arbitrary URL. Therefore, ignore the Authorization and POST sections below as well as the Try It Out button.

Endpoint
POST
{DEPLOYMENT-URI}/v1/getRates
Was this helpful?
Yes
No