About the Billing API

The Billing API allows to charge site owners for using your app.

With the Billing API, you can:

  • Retrieve data about a site's previous paid plans for your app.
  • Redirect site owners to the standard Wix checkout page in case you manage your app's pricing page outside of Wix.
  • Ensure that your app's integration with the Custom Charges service plugin works as intended.

See the App Instance API for more information on how to track data that's associated with individual app instances. Learn more about charging customers varying amounts each billing cycle with the Custom Charges service plugin.

Before you begin

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

  • Wix allows you to manage your app's pricing page either through Wix or externally. You can display up to 4 different plans for your app on the Wix pricing page.
  • In case you manage your pricing page on your own servers, you can still redirect site owners to the standard Wix checkout page by using Get URL.

Use cases

Terminology

  • App instance: Specific occurrence of your app on a particular Wix site.
  • Paid plan: The site owners have installed a version of your app that isn't free of charge. Your app could charge them a single payment or on a subscription basis.
  • Wix pricing page: Wix offers your app an out-of-the-box pricing page that displays up to 4 plans for your app to site owners.
  • Wix checkout: Wix allows you to charge site owners either through the Wix Billing ecosystem or to manage your app's billing externally. In case you manage your app's pricing page on your own servers, you can still redirect site owners to the standard Wix checkout page by using Get URL.
Did this help?

Billing API: Sample Use Cases and 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.

Set up an external pricing page

  1. In your app's Pricing page select External pricing page and provide the URL.
  2. Keep in mind that users can reach your pricing page in two ways: Through your App Market listing: Users who click this link usually want to see your pricing, but probably haven't installed the app yet. Make sure these users can see the pricing without needing to sign up. Or through the Upgrade App button in Manage Apps: We attach a query parameter to your pricing page with the user's App Instance when they click this link. This lets you automatically identify users, log them in, and show them relevant pricing info. Use each user's unique App Instance ID to recognize them as a Wix user and display the right settings.
  3. After a user chooses their preferred version of your app, redirect them to the Wix checkout. You retrieve the URL by calling the App Management API's Get URL endpoint. The lURL is valid for 48 hours, so you need to retrieve the URL regularly.
  4. Once the user completes their purchase, we'll redirect them to the successURL that you've submitted in the API call. If you haven't passed success URL, Wix redirects the user to the default Wix success page.
  5. This triggers the Paid Plan Purchased webhook. You find webhook payload includes the Plan ID. To validate that the user has signed up to a premium plan, call the Get App Instance endpoint to return the user's plan.
  6. Prevent users from downgrading Make sure that users can't downgrade using your External Pricing Page – this includes switching from yearly to monthly pricing. To downgrade, or switch to monthly pricing, users need to cancel their subscription and purchase the cheaper plan. If your app uses an Internal Dashboard, set your Success URL so that it leads back to the Dashboard by using https://www.wix.com/my-account/app/<appID>/<AppInstanceID> During development, all your plans will be automatically set to a price of 0.00, so you can test the flow. Once your app's approved, your plans' real prices will be activated and you'll receive a coupon for testing.
Did this help?

POST

Get Url


Retrieves the URL for a Wix checkout page for the specified paid plan of your app.

This call succeeds only in case you have previously set up an external pricing page in your app's dashboard.

The returned checkout URL is valid for 48 hours.

This API allows your app to manage your pricing page outside of Wix while still using the standard Wix checkout flow.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Your App
Read site, business, and email details
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/apps/v1/checkout

Body Params
productIdstringRequired

ID of your app's paid plan to retrieve the Wix checkout URL for. Check your app's dashboard for a list of your app's supported product IDs.


successUrlstringformat WEB_URL

URL for the Wix checkout page. Redirect site owners to this URL after they've successfully purchased a paid plan for your app.


testCheckoutboolean

Whether the checkout is for testing purposes only. Testing is mainly relevant for in-app purchase flows. When true, Wix charges the site owners an amount of 0.00.


billingCyclestring

Information about the paid plan's billing cycle.


countryCodestring

2-letter country code in ISO-3166 alpha-2 format.

Default: "US"


languageCodestring

2-letter language code in ISO 639-1 alpha-2 format.

Default: "EN"


couponCodestring

Coupon code for the paid plan. Available only in case there is a discount.

Response Object
checkoutUrlstringformat WEB_URL

URL for the Wix checkout page.


tokenstring

Token for the Wix checkout page. The token holds all data about the order you're creating a checkout for. It is signed, so you can verify that it comes from Wix.

Get Url Example 1
Request
cURL
curl -X POST \ https://www.wixapis.com/apps/v1/checkout \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "productId": "e8f429d4-0a6a-468f-8044-87f519a53202", "billingCycle": "MONTHLY" }'
Response
JSON
{ "checkoutUrl": "https://www.wix.com/apps/upgrade/order-checkout?token=JWS.eyJraWQiOiJaUnliMG5pbCIsImFsZyI6IkhTMjU2In0.eyJkYXRhIjoie1wib3JkZXJJdGVtc1wiOlt7XCJwcm9kdWN0SWRdIjpcImIwZjgwOGMzLWM4YmUtNGNkYS1iNmQyLTc0YTExNTM2ZDdiZFwiLFwicXVhbnRpdHlcIjoxLFwicGF5bWVudEN5Y2xlXCI6XCJNT05USExZXCIsXCJkaXNwbGF5TmFtZVwiOlwiXCIsXCJjb3Vwb25Db2RlXCI6bnVsbCxcImJpbGxpbmdTZXJ2aWNlSWRcIjpudWxsLFwib3ZlcnJpZGVQcmljZVwiOlwiOC4wXCIsXCJleHRlcm5hbE9yZGVySXRlbUlkXCI6XCJMaW5lSXRlbV8wXCJ9XSxcInN1Y2Nlc3NVcmxcIjpcImh0dHBzOi8vd3d3LndpeC5jb20vYXBwcy91cGdyYWRlL29yZGVyLXJlc3VsdFwiLFwid2l4VXNlckd1aWRcIjpudWxsLFwidXNlckVtYWlsXCI6bnVsbCxcImxhbmd1YWdlQ29kZVwiOlwiZW5cIixcImN1cnJlbmN5Q29kZVwiOlwiVVNEXCIsXCJvcmRlclBhcmFtc1wiOntcInNpdGVHdWlkXCI6XCIxMTE0MjExNC0yZDExLTRkNzYtOWEzZS0zZjUzMzBiNjBhYzdcIn0sXCJldmVudEFnZ3JlZ2F0b3JcIjpcImYzNGY1MGE4LTc3ZDMtNDE1Ny1iM2Q3LTZiMDJkYzI2ODQ1NlwiLFwiaW5pdGlhdG9yXCI6XCJBcHAgTWFya2V0IFRQQSBBUElcIixcImNvdXBvbkRpc3BsYXlOYW1lXCI6bnVsbH0iLCJpYXQiOjE1NzQ1OTAyMDcsImV4cCI6MTU3NDc2MzAwN30.quYK2ND5tCTsaRPlQA5349ULQoWUwkdPzQEwcQhqc9s&appId=5bc2068d-010b-448c-a62a-d6bb269c5a4c&planId=e8f429d4-0a6a-468f-8044-87f519a53202", "token": "JWS.eyJraWQiOiJaUnliMG5pbCIsImFsZyI6IkhTMjU2In0.eyJkYXRhIjoie1wib3JkZXJJdGVtc1wiOlt7XCJwcm9kdWN0SWRdIjpcImIwZjgwOGMzLWM4YmUtNGNkYS1iNmQyLTc0YTExNTM2ZDdiZFwiLFwicXVhbnRpdHlcIjoxLFwicGF5bWVudEN5Y2xlXCI6XCJNT05USExZXCIsXCJkaXNwbGF5TmFtZVwiOlwiXCIsXCJjb3Vwb25Db2RlXCI6bnVsbCxcImJpbGxpbmdTZXJ2aWNlSWRcIjpudWxsLFwib3ZlcnJpZGVQcmljZVwiOlwiOC4wXCIsXCJleHRlcm5hbE9yZGVySXRlbUlkXCI6XCJMaW5lSXRlbV8wXCJ9XSxcInN1Y2Nlc3NVcmxcIjpcImh0dHBzOi8vd3d3LndpeC5jb20vYXBwcy91cGdyYWRlL29yZGVyLXJlc3VsdFwiLFwid2l4VXNlckd1aWRcIjpudWxsLFwidXNlckVtYWlsXCI6bnVsbCxcImxhbmd1YWdlQ29kZVwiOlwiZW5cIixcImN1cnJlbmN5Q29kZVwiOlwiVVNEXCIsXCJvcmRlclBhcmFtc1wiOntcInNpdGVHdWlkXCI6XCIxMTE0MjExNC0yZDExLTRkNzYtOWEzZS0zZjUzMzBiNjBhYzdcIn0sXCJldmVudEFnZ3JlZ2F0b3JcIjpcImYzNGY1MGE4LTc3ZDMtNDE1Ny1iM2Q3LTZiMDJkYzI2ODQ1NlwiLFwiaW5pdGlhdG9yXCI6XCJBcHAgTWFya2V0IFRQQSBBUElcIixcImNvdXBvbkRpc3BsYXlOYW1lXCI6bnVsbH0iLCJpYXQiOjE1NzQ1OTAyMDcsImV4cCI6MTU3NDc2MzAwN30.quYK2ND5tCTsaRPlQA5349ULQoWUwkdPzQEwcQhqc9s" }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

GET

Get Purchase History


Retrieves a list of the site owner's past purchases for your app.

You don't have to explicitly pass an identifier for the Wix site as part of the request, since this information is taken automatically from the context.

The response doesn't include any details about cancellations.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Your App
Read site, business, and email details
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/apps/v1/checkout/history

Request
This endpoint does not take any parameters.
Response Object
purchasesArray <PurchasedItem>

Retrieved purchases the site owners have completed for you app.

Get Purchase History Example 1
Request
cURL
curl -X GET \ https://www.wixapis.com/apps/v1/checkout/history\ -H 'Authorization: <AUTH>' \
Response
JSON
{ "purchases": [ { "productId": "mid-tier", "price": "0", "currency": "USD", "billingCycle": "YEARLY", "dateCreated": "2020-07-21T08:45:18Z" } ] }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?