About the Custom Charges Service Plugin

As a custom charges provider, you can integrate with Wix to allow a merchant to manage what customers must pay to use an app. This includes regularly recurring base prices, installation and usage fees, and any other custom charges.

The integration is done via an app in the Wix App Market and by implementing the Custom Charges service plugin. After the app is installed on a site, Wix triggers a call to your service when specific actions are taken on the site. Refer to each function's description for details about those actions.

Using the service plugin, you can design your app to:

• Add an app's charges to the invoice that Wix sends to site owners.
• Receive notifications about charges that Wix doesn't accept, created invoices, or when customers increase their charge limit.
• Keep your customers informed about how much an app would charge them if Wix were to send an invoice at this moment.

Before you begin

It’s important to note the following points before starting to code:

Before you can implement the Custom Charges service plugin, it's essential to set up Usage-Based Pricing for the app in the Wix Developers Center. Note that you have to submit a request to enable Usage-Based Pricing. Keep in mind that Usage-Based Pricing is currently in Alpha, this means it's still in development and may change in the future.

• You can't bill your customers before they upgrade to a paid version of the app.
• You're able to include up to 5 custom charges per invoice.
• You must set an initial charge limit and can't bill customers more than this limit per billing cycle. You can't change the limit later, but customers are able to increase it themselves.
• You receive notifications in case Wix doesn't accept the charges you return via the service plugin. Currently, there is no notification if the customer agrees to your proposed charge limit or pays an invoice.
• Currently, Wix supports the following currencies: AUD, BRL, CAD, EUR, GBP, ILS, INR, JPY, MXN, PLN, RUB, TRY, USD. Wix may add more currencies in the future.
• We recommend to use the instanceId instead of the subscriptionId to track usage and billing for apps.
• If we discover that your app has charged customers for usage outside of an invoice's specified period, we may take action such as blocking your app from charging the customer, removing your app from the Wix App Market, revoking your access to the Wix developer program, or pursuing legal action to recover damages caused by overcharging. We understand that mistakes can happen and encourage you to contact the Wix App Market team immediately if you become aware of any overcharging issues so that we can work together to resolve the situation.

Get started

Follow these steps to begin implementing your service plugin.

Choose a framework

You can implement this service plugin with the following frameworks:

• Wix CLI: Learn how to implement a service plugin with the CLI and the SDK.
• Self-hosted: Learn how to implement a self-hosted service plugin with the SDK and the Wix Dev Center.

Configure your service plugin

To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can configure your plugin in the Wix Dev Center. For details, see Custom Charges Extension Configuration.

Define handler functions

Use customCharges.provideHandlers() to define the following handler functions that implement your custom business logic. Make sure you define all required functions.

Code examples

Below is an example for implementing the Custom Charges service plugin in your code.

CLI: Basic code structure

This is the basic code structure for implementing the Custom Charges service plugin with the Wix CLI:

Self-hosted: Basic code structure

This is the basic code structure for implementing a self-hosted Custom Charges service plugin:

See also

• About Service Plugin Extensions
• Add a Service Plugin Extension With the CLI
• Add a Self-hosted Service Plugin With the SDK