Important: Some custom extensions are in Beta. This means that some aren't yet available to all users, and are subject to change.

Velo SPIs (Service Provider Interfaces) provide you with a very powerful way to expand what your Wix site can do. You can extend and customize using SPIs by:

• Injecting your own custom logic into an existing, out-of-the-box app flow. Depending on the SPI, you can address certain aspects of a flow or add a new stage in a flow.
• Integrating 3rd-party services into app flows on your site.

Examples of custom extensions

• When you set up a Wix Store, there are a limited number of payment and shipping rates service providers to choose from. What if you want to use a provider not currently on the list? You can create custom extensions that allow you to add more shipping rate providers to your store's checkout flow. This type of custom extension involves integrating with a 3rd-party service provider.
• The typical eCommerce checkout process does not allow you to add additional fees that are not related to specific line items. You can use custom extensions to add extra fees like charges for gift wrap or fragile items to your checkout flow. This type of custom extension involves injecting your own logic into an existing Wix app flow.

Let's make sure our terms are aligned before we get started.

Term	Description
SPI	Service Provider Interface. A type of API that defines a service, but leaves the implementation of that service to Service Providers. For example, to calculate shipping costs for a customer's order, Wix eCommerce calls the Shipping Rates SPI's getShippingRates() endpoint and passes an 'options' object containing line items, shipping details, etc. The chosen service provider's implementation of getShippingRates() will process the infomation in the options object to calculate the applicable rates, then return an appropriately formatted object containing the rates.
Custom extensions	A feature that lets you extend the services provided on your site using code. You can make these extensions by adding your own custom logic into a Wix app flow, or data received from a 3rd-party into a Wix app flow. Custom extensions are implemented by adding files to backend code files to your site. These files contain code for your custom logic using SPI function calls and are triggered at specific points in the Wix app flow.
Service provider	The entity providing a service, for example, a shipping company. The service is either a Velo service or a 3rd-party service. The interface to the service is coded using Velo SPIs by the Wix user.
Wix user	You, the site owner or contributor responsible for developing the code needed for the custom extension using Velo SPIs. Your code uses your own custom logic or accesses a service provided by a 3rd-party.
Service	Any additional functionality being added to the site that is not part of the original Wix app flow. The interface to the service is coded by the Wix user with the custom extension feature using SPIs. The service can be written by the Wix user or a 3rd-party. If the service is being provided by a 3rd-party, the Wix user writes the code for the interface by accessing 3rd-party's APIs with wix-fetch, and/or using npm packages.
Wix app	The Wix app whose functionality is being extended. For example, Wix eCommerce has several SPIs available for customizing its flows with custom extensions.

A Velo SPI is an SPI that allows you to extend the functionality of your Wix site by injecting your own custom logic into existing app flows and integrating external services with your Wix site. With Velo, the services you provide can be custom logic for your own Velo app flows or integration with 3rd-party services. Each extension consists of a set of backend code files that utilize SPI functions for implementing the extension. Wix apps call the functions automatically at specific points in their flows. The functions receive and return data in a specific format. The returned data is then integrated by the Wix app into its flow. In this sense, custom extensions fulfill a kind of contract. The Wix user commits to providing data in a certain format, and the Wix app commits to using this data in its flows at specific points.

The reference documentation for each SPI function indicates at what point in a flow an app triggers the function. The documentation also outlines the data provided as arguments to the function when it's triggered, and the format of the data that needs to be returned by the function.

How does it work?

1. At certain points, a call to a service is triggered by an app's activity on your Wix site.
2. When triggered, the Wix platform passes the information in the request to the provider. The provider needs this information to provide the service to the Wix platform.
3. Wix processes the request for the service according to the implementation defined in the custom extension files in the backend.
4. The service provider returns the needed information and the Wix platform consumes and/or displays the information.

For example:

1. Whenever a customer checks out a cart...
2. The Wix eCommerce app calls the calculateAdditionalFees() SPI function.
3. This function receives the parameters that it needs from Wix eCommerce (such as the cart, line items, and so on).
4. The function then returns data about additional fees in a specific structure. The app uses the data received from the function to display additional fees in a customer's checkout flow.

You can add any custom logic to calculate the additional fees as long as the function returns your data in the proper structure.

Using this extension, you can avoid having to build a whole new checkout flow just to add additional fees to the basic Wix eCommerce functionality.

Without custom extensions, if you want to change your out-of-the-box app flow just a little, you might have to rewrite large parts of the flow, such as creating a custom checkout page using the Wix eCommerce Checkout API. This could involve writing many lines of code and creating custom collections.

Inherently, because custom extensions only affect a small part of an app's flow, Velo SPIs require fewer lines of code and less maintenance than when working with Velo APIs. So wherever possible, you want to use SPIs.

For more information:

• Understanding the difference between SPIs and APIs

The Custom Extensions feature currently can’t be added to a site when using Git Integration & Wix CLI (Beta).

The process of implementing an SPI in Velo has 3 steps:

1. Create a new extension on your site
2. Implement your extension with custom code
3. Deploy the extension

See the tutorial for each SPI for detailed instructions.

Need help implementing an SPI? Find a professional to help you.

The first step in setting up your new extension is to add it to your site. This process creates a new folder in the Custom Extensions section of the Velo Sidebar (Wix Editor), and in thd Wix IDE's Explorer (Wix Studio) that contains the files for your code.

1. If necessary, add the relevant app to your site, such as Wix Stores.
2. • Wix Editor: Enable Velo Dev Mode, and then click the Public & Backend tab in the Velo Sidebar.
   • Wix Studio: If necessary, click and then Start Coding.
3. • Wix Editor: Scroll down to the Custom Extensions panel at the bottom of the sidebar.
   • Wix Studio: Click Packages & Apps.
4. Hover over Custom Extensions and click to add the integration that you want.
5. Follow the prompts to add the extension and accept any terms and conditions that display.
6. Enter a name for your integration and click Add & Edit Code. The name can't contain spaces or special characters. For Wix Studio sites, open the Wix IDE, and go to /src/backend/spi/. If your Custom Extension doesn't appear, try refreshing both the Studio Editor and the Wix IDE.

The procedure in the previous step creates a folder in the Custom Extensions section of the Velo Sidebar (Wix Editor), or in the Wix IDE's Explorer (Wix Studio). The name of the folder is based on the extension you chose. Inside this is another folder with the name of the extension you set up. This folder contains 2 files, <my-extension-name>.js and <my-extension-name>-config.js.

Default extension files:

• <my-extension-name>.js: The code in this file generally defines a function named after the purpose of the custom extension, such as getShippingRates() or getFees(). The function is called by Wix to retrieve the data provided by your extension.
• <my-extension-name>-config.js: The code in this file generally defines a function that returns an object containing values used to configure your extension.

Implement the custom code for your extension in these files. See the SPI tutorial for each supported custom extension for guidelines for writing your code.

Note: We recommend you use the standard export syntax contained in the SPI code files when they are created. If you wish to use a different export syntax, read Module Export Syntax to learn which formats are supported.

Add more files to an extension

If you don't want to keep all of your code in the main files, you can add files to the extension's folder and import functions and objects into the main files.

• Wix Editor:

  1. Hover over the extension folder's name and click Show More .
  2. Select the New.js file.

• Wix Studio: Create a new file in the extension's folder.

To import from these files to the main files, use the following syntax:

Copy Code
import { functionName } from './myFileName.js';

Test an extension

You can test your extension before publishing your site in the Wix Editor using functional testing like you would any backend Velo code. Make sure your functions' return values are properly formatted.

To test your extension after deploying, add console logs to your code. The results appear in the Site Events log.

Once your code files are ready, publish your site to deploy the extension.

You can remove an extension from your site.

Wix Editor:

1. In the Public & Backend section of the Velo Sidebar, under Custom Extensions, hover over the extension's folder and click Show More .
2. Select Remove.
3. Click Remove.

Wix Studio: Right click on the extension's folder and select Delete Permanently.

If you connect to a 3rd-party provider using SPIs, you agree to the Wix.com Terms of Use. Wix is not responsible for your use of such a 3rd-party provider, and any liability resulting from such use will be your responsibility.

SPI	Description	Resources
eCommerce Shipping Rates	Provide custom shipping rates fees to your store's checkout flow.	Tutorial, SPI Reference
eCommerce Additional Fees	Add additional fees for things like location and special handling to your store's checkout flow.	Tutorial, SPI Reference
eCommerce Catalog (Beta)	Define your own custom catalog and how it interacts with the eCommerce purchase flow.	Tutorial, SPI Reference
Bookings Custom Pricing	Customize pricing for bookings to offer varied pricing to the bookings purchase flow.	Tutorial, SPI Reference