About the Custom Charges Service Plugin

The Custom Charges service plugin (formerly 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 service plugin, 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 app dashboard:

  • 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 service plugin, it's essential to set up Usage-Based Pricing for your app in the app dashboard. 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 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, because this field is also used in the App Instance 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

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 a service plugin 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 Instance API.
Did this help?

Custom Charges Service Plugin: 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.
Did this help?

POST

Get Charge Limit


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Wix calls this method to retrieve the initial charge limit for a paid instance of your app. This happens every time a customer is upgrading to a paid version of your app.

You can't update the charge limit after you've set an initial value. Customers can increase the limit in their site's dashboard, currently they aren't allowed to decrease it.

Endpoint
POST
{DEPLOYMENT-URI}/v1/charge-limit
Body Params
subscriptionIdstringformat GUID

ID of the subscription for which Wix retrieves the charge limit. Equals null in case Wix hasn't created the subscription when retrieving an initial charge limit. To track usage and billing for apps, we recommend to use instanceId instead of the subscriptionId.


currencystringformat CURRENCY

Supported values: AUD, BRL, CAD, EUR, GBP, ILS, INR, JPY, MXN, PLN, RUB, TRY, USD.

3-letter currency code in ISO-4217 alphabetic format of the charge limit. Wix may add supported currencies in the future.

Response Object
chargeLimitstringformat DECIMAL_VALUEdecimalValue {"gt":"0.00"}

Retrieved charge limit for the app instance. You can't update the charge limit after you've set an initial value. Site owners can increase the limit in their site's dashboard, currently they aren't allowed to decrease it.

Return an app instance's initial charge limit.

The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.

Request
cURL
curl -X POST \ 'https://provider.example.com/v1/charge-limit' \ -H 'Authorization: <AUTH>' \ -d '{ "data": { "request": { "subscriptionId": "efa6b37d-74c6-44bb-b639-28c4af3957dd", "currency": "USD" }, "metadata": { "requestId": "1680014776.67327419774788218037", "identity": { "identityType": "APP", "appId": "365288ae-38f4-4932-92d5-d45c596c7260" }, "instanceId": "3aa496c3-aa49-4369-84e6-3fa1876f191d" } }, "aud": "6675724b-bf3e-482a-9a00-65616953b570", "iss": "wix.com", "iat": 1680014777, "exp": 1683614777 }'
Response
JSON
{ "chargeLimit": "1000.00" }
Did this help?

POST

List Charges


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Wix calls this method to retrieve a list of charges for a paid instance of your app. This happens when Wix creates an invoice or in case the customer wants to preview how much your app would charge them at the moment.

You must return the charges in the currency that's specified in the request, you aren't allowed to return more than 5 charges, and their sum must be lower than the charge limit.

You may not bill customers for any usage that didn’t occur during the period Wix specifies when retrieving the charges. If Wix discovers 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.

Endpoint
POST
{DEPLOYMENT-URI}/v1/charges
Body Params
subscriptionIdstringformat GUID

ID of the subscription for which Wix retrieves your custom charges. To track usage and billing for apps, we recommend to use instanceId instead of the subscriptionId.


currencystringformat CURRENCY

Supported values: AUD, BRL, CAD, EUR, GBP, ILS, INR, JPY, MXN, PLN, RUB, TRY, USD.

3-letter currency code in ISO-4217 alphabetic format of your charges to return. Wix may add supported currencies in the future.


periodStartstringformat date-time

Begin of the period Wix retrieves the app instance's charges for in YYYY-MM-DDThh:mm:ss.sssZ format.


periodEndstringformat date-time

End of the period Wix retrieves the app instance's charges for in YYYY-MM-DDThh:mm:ss.sssZ format.


intentstring

Information about what Wix intends to do with the retrieved charges.

Response Object
chargesArray <ChargeLineItem>maxItems 5

Retrieved charges.

Max: 5 charges

Return your app's custom charges.

The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.

Request
cURL
curl -X POST \ 'https://provider.example.com/v1/charges' \ -H 'Authorization: <AUTH>' \ -d '{ "data": { "request": { "subscriptionId": "efa6b37d-74c6-44bb-b639-28c4af3957dd", "currency": "USD", "periodStart": 1677674012000, "periodEnd": 1680179612000, "intent": "CREATE_INVOICE" }, "metadata": { "requestId": "1680014776.67327419774788218037", "identity": { "identityType": "APP", "appId": "365288ae-38f4-4932-92d5-d45c596c7260" }, "instanceId": "3aa496c3-aa49-4369-84e6-3fa1876f191d" } }, "aud": "6675724b-bf3e-482a-9a00-65616953b570", "iss": "wix.com", "iat": 1680014777, "exp": 1683614777 }'
Response
JSON
{ "charges": [ { "id": "Some Charge Id 1", "description": "Setup fee", "amount": "200.00" }, { "id": "Some Charge Id 2", "description": "Usage charges", "amount": "300.00" } ] }
Did this help?

POST

Charges Rejected Event


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered in case Wix doesn't accept the charges you've returned in the List Charges method.

You aren't allowed to charge a site owner more than the charge limit. Wix call List Charges in regular intervals until the sum of all charges is lower than the charge limit. Wix doesn't create an invoice in case the charges aren't accepted.

Endpoint
POST
{DEPLOYMENT-URI}/v1/charges-rejected
Body Params
subscriptionIdstringformat GUID

ID of the subscription for which Wix hasn't accepted your custom charges. To track usage and billing for apps, we recommend to use instanceId instead of the subscriptionId.


currencystringformat CURRENCY

Supported values: AUD, BRL, CAD, EUR, GBP, ILS, INR, JPY, MXN, PLN, RUB, TRY, USD.

3-letter currency code in ISO-4217 alphabetic format of the charges. Wix may add supported currencies in the future.


chargeIdsArray <string>maxItems 5

IDs of the rejected charges.

Max: 5 charges


chargeLimitstringformat DECIMAL_VALUEdecimalValue {"gt":"0.00"}

Maximum amount that your app may charge the customer per billing cycle.

Min: 0.50


reasonsArray <string>maxItems 20

Information about why Wix has rejected your app's charges.

Max: 20 reasons

Response Object
Returns an empty object.
Get notified when Wix doesn't accept your custom charges.

The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.

Request
cURL
curl -X POST \ 'https://provider.example.com/v1/charges-rejected' \ -H 'Authorization: <AUTH>' \ -d '{ "data": { "request": { "subscriptionId": "efa6b37d-74c6-44bb-b639-28c4af3957dd", "currency": "USD", "chargeIds": [ "Some Charge Id 1", "Some Charge Id 2" ], "chargeLimit": "1000.00", "reasons": [ "CHARGE_LIMIT_EXCEEDED" ] }, "metadata": { "requestId": "1680014776.67327419774788218037", "identity": { "identityType": "APP", "appId": "365288ae-38f4-4932-92d5-d45c596c7260" }, "instanceId": "3aa496c3-aa49-4369-84e6-3fa1876f191d" } }, "aud": "6675724b-bf3e-482a-9a00-65616953b570", "iss": "wix.com", "iat": 1680014777, "exp": 1683614777 }'
Response
JSON
{}
Did this help?

POST

Invoice Created Event


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered in case Wix creates an invoice that includes charges for an instance of your app.

Endpoint
POST
{DEPLOYMENT-URI}/v1/invoice-created
Body Params
subscriptionIdstringformat GUID

ID of the subscription for which Wix has created an invoice that includes your custom charges. To track usage and billing for apps, we recommend to use instanceId instead of the subscriptionId.


currencystringformat CURRENCY

Supported values: AUD, BRL, CAD, EUR, GBP, ILS, INR, JPY, MXN, PLN, RUB, TRY, USD.

3-letter currency code in ISO-4217 alphabetic format of the charges. Wix may add supported currencies in the future.


invoiceIdstring

ID of the created invoice.


lineItemsArray <InvoiceLineItem>maxItems 5

Line items included in the invoice.

Response Object
Returns an empty object.
Get notified when Wix creates an invoice with your custom charges.

The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.

Request
cURL
curl -X POST \ 'https://provider.example.com/v1/invoice-created' \ -H 'Authorization: <AUTH>' \ -d '{ "data": { "request": { "subscriptionId": "efa6b37d-74c6-44bb-b639-28c4af3957dd", "currency": "USD", "invoiceId": 43434213, "lineItems": [ { "chargeId": "Some Charge Id 1", "amount": "200.00", "id": "f322c4bf-7edb-42f8-b0c2-162b51d4ad75" }, { "chargeId": "Some Charge Id 2", "amount": "300.00", "id": "4faa44b4-654c-411d-803d-be816e03726e" } ] }, "metadata": { "requestId": "1680014776.67327419774788218037", "identity": { "identityType": "APP", "appId": "365288ae-38f4-4932-92d5-d45c596c7260" }, "instanceId": "3aa496c3-aa49-4369-84e6-3fa1876f191d" } }, "aud": "6675724b-bf3e-482a-9a00-65616953b570", "iss": "wix.com", "iat": 1680014777, "exp": 1683614777 }'
Response
JSON
{}
Did this help?

POST

Charge Limit Updated Event


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered in case the charge limit for an instance of your app is updated.

You can't update the charge limit after you've set an initial value. Site owners can increase the limit in their site's dashboard, currently they aren't allowed to decrease it.

Endpoint
POST
{DEPLOYMENT-URI}/v1/limit-updated
Body Params
subscriptionIdstringformat GUID

ID of the subscription for which the charge limit has been updated. To track usage and billing for apps, we recommend to use instanceId instead of the subscriptionId.


currencystringformat CURRENCY

Supported values: AUD, BRL, CAD, EUR, GBP, ILS, INR, JPY, MXN, PLN, RUB, TRY, USD.

3-letter currency code in ISO-4217 alphabetic format of the charges. Wix may add supported currencies in the future.


chargeLimitstringformat DECIMAL_VALUE

Updated charge limit.

Response Object
Returns an empty object.
Get notified when a customer updates the charge limit.

The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.

Request
cURL
curl -X POST \ 'https://provider.example.com/v1/limit-updated' \ -H 'Authorization: <AUTH>' \ -d '{ "data": { "request": { "subscriptionId": "efa6b37d-74c6-44bb-b639-28c4af3957dd", "currency": "USD", "chargeLimit": "1000.00" }, "metadata": { "requestId": "1680014776.67327419774788218037", "identity": { "identityType": "APP", "appId": "365288ae-38f4-4932-92d5-d45c596c7260" }, "instanceId": "3aa496c3-aa49-4369-84e6-3fa1876f191d" } }, "aud": "6675724b-bf3e-482a-9a00-65616953b570", "iss": "wix.com", "iat": 1680014777, "exp": 1683614777 }'
Response
JSON
{}
Did this help?