Velo: Custom App Extensions Using SPIs

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.

Terminology

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.

What is a Velo SPI?

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.

Velo APIs and SPIs: When to use which?

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

Implementing a custom extension with a Velo SPI

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.

Step 1. Create a new extension on your Wix site

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 Code sidebar (Wix Studio), or the Velo sidebar (Wix Editor).

1. If necessary, add the relevant app to your site, such as Wix Stores.
2. Enable coding:
   • Wix Studio: If necessary, click and then Start Coding.
   • Wix Editor: Enable Velo Dev Mode.
3. Go to the Public & Backend section of the Code sidebar (Wix Studio), or the Velo Sidebar (Wix Editor).
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.

Step 2. Implement your extension with custom code

The procedure in the previous step creates a folder under Custom Extensions in the Public & Backend section of the Code sidebar (Wix Studio), or the Velo sidebar (Wix Editor). 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>-config.js and <my-extension-name>.js.

Default extension files:

• <my-extension-name>-config.js: The code in this file generally defines a function, getConfig(), that returns an object containing values used to configure your extension. Wix calls this function when you publish your site. Changes to the configuration don't take effect until you publish your site.
• <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(). Wix calls this function to retrieve the data provided by 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.

Test an extension

You can test your extension before publishing your site in the 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.

Step 3. Deploy the extension

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

Remove an extension

You can remove an extension from your site.

1. In the Public & Backend section of the Code sidebar (Wix Studio), or the Velo Sidebar, under Custom Extensions, hover over the extension's folder and click the Show More icon .
2. Click Delete.

Legal notices

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.

Available Custom Extensions

SPI	Description	Resources
Bookings Custom Pricing	Customize pricing for bookings to offer varied pricing to the bookings purchase 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
eCommerce Payment Settings	Apply custom payment settings during the payment process of an order.	Tutorial, SPI Reference
eCommerce Shipping Rates	Provide custom shipping rates fees to your store's checkout flow.	Tutorial, SPI Reference
eCommerce Validations	Validate a site visitor's cart and checkout.	Tutorial, SPI Reference
Payments Payment Provider	Provides functionality for integrating your site with payment providers not currently supported by Wix.	Tutorial, SPI Reference