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

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

Errors

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

Did this help?