Service Plugins (formerly SPIs)

Velo service plugins provide you with a very powerful way to expand what your Wix site can do. You can extend and customize using plugins by:

• Injecting your own custom logic into an existing, out-of-the-box app flow. Depending on the plugin, 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 service plugins

• 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 service plugins that allow you to add more shipping rate providers to your store's checkout flow. This type of service plugin 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 service plugins to add extra fees like charges for gift wrap or fragile items to your checkout flow. This type of service plugin 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
Service plugins (formerly SPIs and custom extensions)	A feature that lets you extend the services provided on your site using code. You can make these plugins by adding your own custom logic into a flow for an app made by Wix, or by adding data received from a 3rd-party into a flow for an app made by Wix. Service plugins are implemented by adding files to backend code files to your site. These files contain code for your custom logic function calls and are triggered at specific points in the app-made-by-Wix flow. These custom logic function calls are based on 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 getShippingRates() endpoint and passes an options object containing line items, shipping details, and so on, to the service provider. The service provider's implementation of getShippingRates() processes the information in the options object to calculate the applicable rates, and then returns an appropriately-formatted object containing the rates back to Wix eCommerce.
Service provider	The entity providing a service, for example, a shipping company. The service is either a Velo service or a 3rd-party service.
Wix user	You, the site owner or contributor responsible for developing the code needed for the service plugin. 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 service plugin feature. 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 Service Plugins available for customizing its flows.

What is a Velo Service Plugin?

A Velo service plugin 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 plugin consists of a set of backend code files that utilize a type of API functions for implementing the plugin. 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, service plugins 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 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 service plugin 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() 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 plugin, 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 service plugin functions: When to use which?

Without service plugins, 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 service plugins only affect a small part of an app's flow, Velo service plugin functions require fewer lines of code and less maintenance than when working with Velo APIs. So wherever possible, you want to use service plugin functions.

For more information:

• Understanding the difference between service plugins and APIs

Implementing a service plugin

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

The process of implementing a service plugin in Velo has 3 steps:

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

See the tutorial for each service plugin for detailed instructions.

Need help implementing a service plugin? Find a professional to help you.

Step 1. Create a new service plugin on your Wix site

The first step in setting up your new service plugin is to add it to your site. This process creates a new folder in the service plugin 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 Service Plugins and click to add the integration that you want.
5. Follow the prompts to add the plugin 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 service plugin with custom code

The procedure in the previous step creates a folder under Service Plugins 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 plugin you chose. Inside this is another folder with the name of the plugin you set up. This folder contains 2 files, <my-plugin-name>-config.js and <my-plugin-name>.js.

Default extension files:

• <my-plugin-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-plugin-name>.js: The code in this file generally defines a function named after the purpose of the service plugin, 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 tutorial for each supported service plugin 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 Wix Logs.

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 Service Plugins, 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 service plugins, 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 Service Plugins

Service Plugin	Description	Resources
Bookings Custom Pricing	Customize pricing for bookings to offer varied pricing to the bookings purchase flow.	Tutorial, Reference
External Database Collection	Use external databases.	Reference
Billing Tax Calculation	Customize your tax calculations.	Reference
Automations Action	Write a custom action instead of selecting a pre-made action.	Reference
eCommerce Additional Fees	Add additional fees for things like location and special handling to your store's checkout flow.	Tutorial, Reference
eCommerce Catalog (Beta)	Define your own custom catalog and how it interacts with the eCommerce purchase flow.	Tutorial, Reference
eCommerce Discount Triggers	Apply discount rules to a site visitor’s cart and checkout.	Tutorial, Reference
eCommerce Payment Settings	Apply custom payment settings during the payment process of an order.	Tutorial, Reference
eCommerce Shipping Rates	Provide custom shipping rates fees to your store's checkout flow.	Tutorial, Reference
eCommerce Validations	Validate a site visitor's cart and checkout.	Tutorial, Reference
Payments Payment Provider	Provides functionality for integrating your site with payment providers not currently supported by Wix.	Tutorial, Reference
Form Submission	Provides additional form submission validation.	Tutorial, Reference