About the Custom Charges SPI

The Custom Charges SPI allows you to manage what customers must pay to use your app. This includes regularly recurring base prices, installation and usage fees, and any other custom charges.

With the Custom Charges SPI, you can:

• Add your 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 your app would charge them if Wix were to send an invoice at this moment.

See the App Instance API for more details about the notifications you receive when a customer installs an instance of your app on their site.

How to become a provider

When configuring your app in the Wix Developers Center:

• Set up Usage-Based Pricing for your app. Note that Usage-Based Pricing is in Alpha and may change in the future.
• Add a Premium Custom Charges integration component.
• Use the JSON editor to update the baseUri. Make sure to include only the base part of your integration's URI. For example, if Wix should call your integration at https://provider.example.com/v1/charge-limit for the Get Charge Limit endpoint set {"baseUri": "https://provider.example.com"}.

Before you begin

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

• Before you can implement the Custom Charges SPI, it's essential to set up Usage-Based Pricing for your 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 your 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 SPI. 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, because this field is also used in the App Management API.
• 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.

Use cases

• Support app upgrades
• Bill a customer
• Get Notified when an app instance is canceled

Terminology

• App instance: Particular installation of an app that let's you identify your customer. Learn more about how to retrieve the instance ID from an SPI request envelope.
• Customer: Site owner who installs your app on their Wix site.
• Invoice: Document that Wix sends to customers specifying the price they have to pay for using the Wix platform. Includes charges for 3rd-party apps associated with the site.
• Charge: Price for using your app that you can add to an invoice. You can add up to 5 charges per invoice.
• Charge limit: Maximum amount that you're allowed to charge customers for using your app per billing cycle. It helps ensure that customers are aware of their potential costs upfront.
• Subscription ID: Unique identifier for the agreement that specifies the product or service to which the customer has access to and how they are billed. Currently, Wix doesn't provide an API to retrieve information about subscriptions. In case the product is an app, we recommend to use the app instance ID instead of the subscription ID to track usage and billing, because this field is also used in the App Management API.

Custom Charges SPI: Sample Use Cases & Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Support app upgrades

Every time a customer upgrades an instance of your app, Wix retrieves an initial charge limit from your app. Wix displays this limit to the customer in the checkout page of the upgrade process. This helps customers understand how much they may have to pay maximally for using your app per billing cycle.

To support app upgrades:

1. Wix calls Get Charge Limit.
2. Return the initial charge limit that your app is allowed to charge the customer per billing cycle.
3. Wix displays the limit to the customer for approval. Note that your app can't change this limit later, but customers are able to increase it themselves.

Bill a customer

Your app can add custom charges to an invoice that Wix sends to a customer at the end of the billing cycle.

To bill a customer:

1. Wix calls List charges. Note that Wix sends {"intent": "CREATE_INVOICE"} to actually create an invoice with the charges you return. For other purposes, Wix sends {"intent": "DISPLAY_ONLY"}.
2. Return up to 5 charges that Wix adds to the invoice.
3. In case Wix accepts your charges, Wix calls Invoice Created Event and sends the invoice to the customer.

Get notified when an app instance is canceled

Currently, you can't receive notifications when a payment for an invoice has failed. If that happens, Wix sends an email to the customer and retries to collect the payment several times. In case all retries fail, Wix cancels the app instance. Your app could get notified in this situation, and you could reach out to the customer.

To receive notifications when an app instance is canceled:

1. Sign up for the Paid Plan Auto Renewal Cancelled Webhook of the App Instance API.
2. Listen to the webhook. Wix sends {"cancelReason": "FAILED_PAYMENT"} in case an app instance is canceled due to a failed payment.
3. Reach out to the relevant customer.