Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# 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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::5a829a3f-423e-484e-80c5-b70320bf9383slug::introduction*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/introduction)
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](fallback::https://dev.wix.com/docs/rest/internal-only/premium/custom-charges-spi/introduction).

## 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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::dc679a41-44f4-430d-897e-808d0c8f1dd7slug::get-url*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/billing/get-url).

## Use cases

+ [Set up an external pricing page](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::dc679a41-44f4-430d-897e-808d0c8f1dd7slug::sample-flows#set-up-an-external-pricing-page*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/billing/sample-flows#set-up-an-external-pricing-page)

## 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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::dc679a41-44f4-430d-897e-808d0c8f1dd7slug::get-url*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/billing/get-url).

# 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 the Dev Center choose external pricing page and provide the URL.
1. 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](fallback::../General/App%20Instance%20Client%20Side.md) 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](fallback::../General/Identify%20Users%20with%20App%20Instance%20ID.md) to recognize them as a Wix user and display the right settings.
1. 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](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::dc679a41-44f4-430d-897e-808d0c8f1dd7slug::introduction*fallback::https://dev.wix.com/api/rest/app-management/apps/billing/introduction)
   endpoint. The lURL is valid for 48 hours, so you need to retrieve the URL
   regularly.
1. 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.
1. This triggers the [Paid Plan Purchased webhook](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::5a829a3f-423e-484e-80c5-b70320bf9383slug::paid-plan-purchased*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/paid-plan-purchased).
   You find  webhook payload includes the **Plan ID**.
   To validate that the user has signed up to a premium plan, call the [App Instance endpoint](fallback::https://dev.wix.com/api/app-management#apps.app-instance.get-app-instance) to return the user's plan.
1. 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.

identityType

IdentificationData

WebhookIdentityType

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

data

eventType

The identification type and identity data.

instanceId

MessageEnvelope

amount

description

ID of the custom charge. The ID consists of 64 characters.

Charge

Override 3-letter currency code in
[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format.

currency

Override price. In case you omit the override price, Wix charges site
owners the app's default price that's configured in the Wix Developers
Center.

price

ChargeOverride

3-letter currency code in
[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format.

End of the period you want to retrieve the custom charges for in
`YYYY-MM-DDThh:mm:ss.sssZ` format.

endDate

Start of the period you want to retrieve the custom charges for in
`YYYY-MM-DDThh:mm:ss.sssZ` format.

startDate

GetMeteredBillingChargesRequest

charges

GetMeteredBillingChargesResponse

GetPurchaseHistoryRequest

Retrieved purchases the site owners have completed for you app.

purchases

GetPurchaseHistoryResponse

GetSitePaymentMethodsStatusRequest

Whether the site owners accept offline payments.

offlineProviderEnabled

Whether the site owners have enabled at least a single online payment method.
Online payment methods include Wix Payments, Stripe, PayPal, and credit
cards.

onlineProviderEnabled

Whether the site owners have enabled at least one 3rd-party point-of-sale
provider. This allows their customers to make electronic payments in person.

thirdPartyPosProviderEnabled

Whether the site owners have enabled the
[Wix Point of Sale](https://www.wix.com/pos).
This allows their customers to make electronic payments in person.

wixPosProviderEnabled

GetSitePaymentMethodsStatusResponse

Information about the paid plan's billing cycle.

billingCycle

2-letter country code in
[ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
format.

Default: `"US"`

countryCode

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

couponCode

2-letter language code in
[ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format.

Default: `"EN"`

languageCode

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

productId

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

successUrl

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`.

testCheckout

GetUrlRequest

checkoutUrl

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.

token

GetUrlResponse

InvoiceStatus

App instance ID - a unique ID assigned to each app in each site.

invoiceId

Whether the invoice is for a single payment or for multiple, recurring payments.

recurring

status

InvoiceStatusUpdate

PaymentCycle

Information about the billing cycle for your app's paid plan.

Date and time the site onwers have purchased your app's paid plan in
`YYYY-MM-DDThh:mm:ss.sssZ` format.

dateCreated

Price of your app's paid plan. For example, `9.95`.

PurchasedItem

value

StringValue

nanos

seconds

Timestamp

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 the Wix Developers Center](https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/set-up-an-external-pricing-page).

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.

Manage Your App

GetUrl

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.

GetPurchaseHistory

>**Note:** Currently only supported for invoices that use [Metered Billing Charges](https://dev.wix.com/docs/rest/api-reference/app-management/apps/billing/get-metered-billing-charges).

Triggered when there is an update to the payment status of an invoice that includes
custom charges for your app. The [Custom Charges SPI](https://dev.wix.com/api/rest/drafts/custom-charges-spi/introduction?branch=custom-charges-spi)
lets you manage monthly charges associated with your app.
At the end of a billing cycle, Wix calls [List Charges](https://dev.wix.com/api/rest/drafts/custom-charges-spi/list-charges?branch=custom-charges-spi)
to determine the total amount the site owner must pay for using your
app. The charges may be based on usage.

Get Purchase History

Permission Scopes