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:
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.
When configuring your app in the app dashboard:
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/"}
.It’s important to note the following points before starting to code:
AUD
, BRL
, CAD
, EUR
,
GBP
, ILS
, INR
, JPY
, MXN
, PLN
, RUB
, TRY
, USD
. Wix may add
more currencies in the future.instanceId
instead of the subscriptionId
to track
usage and billing for apps, because this field is also used in the
App Instance API.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.
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:
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:
{"intent": "CREATE_INVOICE"}
to actually create an invoice with the charges you return. For other purposes, Wix sends {"intent": "DISPLAY_ONLY"}
.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:
{"cancelReason": "FAILED_PAYMENT"}
in case an app instance is canceled due to a failed payment.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.
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
.
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.
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.
The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.
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
}'
{
"chargeLimit": "1000.00"
}
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.
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
.
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.
Begin of the period Wix retrieves the app instance's charges for in
YYYY-MM-DDThh:mm:ss.sssZ
format.
End of the period Wix retrieves the app instance's charges for in
YYYY-MM-DDThh:mm:ss.sssZ
format.
Information about what Wix intends to do with the retrieved charges.
Retrieved charges.
Max: 5 charges
The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.
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
}'
{
"charges": [
{
"id": "Some Charge Id 1",
"description": "Setup fee",
"amount": "200.00"
},
{
"id": "Some Charge Id 2",
"description": "Usage charges",
"amount": "300.00"
}
]
}
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.
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
.
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.
IDs of the rejected charges.
Max: 5 charges
Maximum amount that your app may charge the customer per billing cycle.
Min: 0.50
Information about why Wix has rejected your app's charges.
Max: 20 reasons
The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.
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
}'
{}
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.
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
.
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.
ID of the created invoice.
Line items included in the invoice.
The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.
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
}'
{}
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.
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
.
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.
Updated charge limit.
The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.
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
}'
{}