About the Wix eCommerce Additional Fees SPI

As an additional fees calculation service provider, you can integrate your service with Wix to allow merchants to request and use your services on their Wix sites. By integrating your service with Wix, the additional fees are then included 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 Additional Fees SPI.

Using the SPI, you can design your app to calculate various additional fees for your merchant's customers, including:

  • Fragile packaging fees
  • Shipping insurance fees
  • Item warranty fees
  • Gift wrapping fees
  • Carbon offset fees

Learn more about implementing an SPI with Wix.

Before you begin

It's important to note that when Wix calls your implementation of the Calculate Additional Fees SPI endpoint, the app must return fees in the same currency as the Wix site. Extract the currency for a site from the request envelope to ensure the correct currency is used in your calculation.

Terminology

Prerequisites

Follow these steps to customize Wix system's integration and enable merchants and their customers to access your additional fees calculations.

  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 Additional Fees 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 Calculate Additional Fees endpoint at https://my-additional-fees.com/v1/calculateAdditionalFees, the base URI you provide here is https://my-additional-fees.com/.
    componentNamestringA unique name for this component. This is an internal name that will only appear in the Dev Center.
  6. Click Test Your App.

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 Additional Fees integration.

Configuration flow

  1. A site owner installs and authorizes your 3rd-party app to provide additional fee calculations based on various factors (line items, shipping info, and buyer details). 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 additional fees calculated for eCommerce orders

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

  2. Wix sends a Calculate Additional Fees SPI request to your app. The payload will include some or all of the fields described in the Body Params and example sections of Calculate Additional Fees. The payload will also include the currency in a context parameter in the request envelope.

  3. Your Additional Fees integration triggers the required flow on its platform and processes the request.

    Wix expects an object containing the additional fees calculated, the currency of those fees, and either a 4xx HTTP status code or a 200 HTTP status code.

    Example of a successful response from your app:

    Copy
    1
    {
    2
    "currency": "USD",
    3
    "additionalFees": [
    4
    {
    5
    "code": "fragile-fee",
    6
    "name": "Fragile Packaging Fee",
    7
    "price": "3",
    8
    "taxDetails": {
    9
    "taxable": true
    10
    }
    11
    }
    12
    ]
    13
    }
  4. The Wix site displays the additional fees on the cart or checkout page (depending on which page triggered the SPI request). The customer can confirm the additional fees before proceeding to payment.

Was this helpful?
Yes
No

Object

Was this helpful?
Yes
No

PostCalculate Additional Fees

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 additional fees calculated by your app.

Wix calls this endpoint when certain actions are performed on the cart or checkout. For example, when an item is added to the cart or the amount of an item is updated in the checkout.

Notes:

  • The currency returned in the response object must match the wix site's currency or those fees will be filtered out and not returned. Extract the currency from the request envelope to ensure the correct currency is used in your calculation.
  • 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/calculate-additional-fees
Was this helpful?
Yes
No