> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: Sample Flows ## Article: Sample Flows ## Article Link: https://dev.wix.com/docs/api-reference/app-management/app-billing/billing/sample-flows.md ## Article Content: # Billing API: Sample Flows This article presents possible use cases and corresponding sample flows that you can support. This article can be a helpful jumping-off point as you plan your implementation. These flows apply to apps that use an external pricing page with Wix-processed payments. If you process payments yourself, you must report all billing events to Wix using the [External Billing Events API](https://dev.wix.com/docs/rest/app-management/app-billing/external-billing-events/introduction.md) and submit quarterly reports. For complete requirements, see [Reporting For Partner Billed Apps](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/partner-billed-apps-reporting.md). > **Note:** The Billing API supports subscription-based plans by default. For 1-time payments or usage-based billing, use the [Custom Charges service plugin](https://dev.wix.com/docs/rest/app-management/app-billing/custom-charges-service-plugin/introduction.md). ## Set up an external pricing page When a visitor browses an app you build on the App Market, you can offer an external pricing page to show plans and pricing. This option lets you customize the pricing experience and guide potential customers through purchase or upgrade flows. Your pricing page needs to handle different scenarios for both existing app users and new visitors: - **Installed app site visitors:** When site visitors click **Upgrade App** on the **Manage Apps** page, Wix attaches an `instance` query parameter to the pricing page URL. Use the instance query parameter to recognize visitors and display their current billing information. - **App Market visitors:** Visitors who click the pricing link from an **App Market** listing usually want to see pricing but probably haven't installed the app yet. Your pricing page should detect when there's no `instance` query parameter and display public pricing information. To set up an external pricing page and handle the complete purchase journey: 1. In the code of your external pricing page, use each Wix user's unique app instance ID to recognize them and display the right information. Call [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md) with the instance token to retrieve their current billing information. 2. In the code of your external pricing page, after a Wix user chooses their preferred plan, redirect them to the Wix checkout. Call [Get URL](https://dev.wix.com/docs/api-reference/app-management/app-billing/billing/get-url.md) to retrieve the checkout URL. The URL is valid for 48 hours, so generate it on demand when the Wix user clicks to purchase. 3. Once the Wix user completes their purchase, Wix redirects them to the `successUrl` that you specify when you call `Get URL`. If you don't specify a `successUrl`, Wix redirects them to the default Wix success page. For apps with an internal dashboard, set the `successUrl` to `"https://www.wix.com/account/app//"` to redirect Wix users directly to their app dashboard. 4. The purchase triggers the [Paid Plan Purchased](https://dev.wix.com/docs/api-reference/app-management/app-instance/paid-plan-purchased.md) event. Handle this event in your backend. The event response includes the Plan ID. To validate that the Wix user has signed up for a premium plan, call [Get App Instance](https://dev.wix.com/docs/api-reference/app-management/app-instance/get-app-instance.md) to confirm the Wix user's plan. 5. In the app's **Pricing & Plans** settings on the **app dashboard**, select **External pricing page** and enter the pricing page URL. 6. Test your pricing page flow. During development, Wix automatically sets all plans to a price of $0.00, so you can test the flow. Once Wix approves the app, Wix activates the plans' real prices. You can then [generate coupons for testing](https://dev.wix.com/docs/build-apps/launch-your-app/app-promotion/create-a-coupon.md).
Prevent Wix users from downgrading using the external pricing page. This restriction includes switching from annual to monthly pricing. To downgrade or switch to monthly pricing, Wix users must cancel their subscription first, then purchase a new plan.