> 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: The App Purchase Lifecycle in Wix

## Article: The App Purchase Lifecycle in Wix

## Article Link: https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/the-app-purchase-lifecycle-in-wix.md

## Article Content:

# The App Purchase Lifecycle in Wix

This article outlines the optional stages a Wix user may go through when installing an app, which include signing up for a free trial, upgrading to a paid plan, and canceling their subscription. By understanding the various stages, from installation and initial setup to free trials and billing cycles, you can effectively manage user interactions, troubleshoot issues, and optimize app sales.   

The app lifecycle can include the following stages:
1. Installation and initial setup
2. Upgrade - with or without a free trial
3. First billing cycle
4. Cancellation

All stages after installation are optional, based on the Wix user's choices.

## Stage 1 | Installation and initial setup

The lifecycle begins when a Wix user decides to install your app.

1. The user initiates the installation by clicking **Add to Site**. 
2. The user reviews the app’s permissions and gives consent, affirming their agreement to the terms.

   > **Note:** The [App Instance Installed webhook](https://dev.wix.com/docs/rest/app-management/app-instance/app-instance-installed.md) is triggered.

3. Your app should collect [app instance](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances.md) data and store the user’s instance ID for subsequent interactions and associations. If using custom authentication (legacy), the app should also collect the refresh token.
4. Your app should restrict access to paid features by default. The app should display a clear call-to-action (CTA), encouraging users to upgrade for a fuller experience. Learn more about [creating an entry point to your pricing page](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/set-up-a-premium-business-model.md#step-4--create-an-upgrade-entry-point-to-your-pricing-page).  
5. Your app should [identify the user](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/identify-and-manage-app-users.md) when they take an action, confirm whether the user has a free or paid version of the app, and manage their access to paid features accordingly.

### How to check if the user installed a free version of the app
- **SDK/REST calls**: Call [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md) and check if `isFree: true`, indicating that the user is currently on a free plan.
- **iFrame apps**: Check the [instance parameter](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/parse-the-app-instance-query-parameter.md) appended to your iframe URL when a user opens the app. No `vendorProductId` will be included.

## Stage 2 | Upgrade flow

There are 2 possibilities when users upgrade an app:
- With a free trial
- Without a free trial

Learn more about [free trials for Wix apps](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/set-up-and-manage-free-trials.md).

### Upgrade with a free trial

1. The user initiates purchase of a paid version of your app (or a plan that costs more than the one they currently have) by clicking **Upgrade**, which brings them to the upgrade process.
2. The user is offered a free trial, if one is available. The initial cost is $0, and Wix collects the user’s credit card information, making users aware of automatic charges that occur after the trial.
3. The user signs up for the free trial.

   <blockquote class="important">
  
   __Important:__  The [Paid Plan Purchased webhook](https://dev.wix.com/docs/rest/app-management/app-instance/paid-plan-purchased.md) is triggered when a user signs up for a free trial. This event won't be triggered again when the free trial expires.
   </blockquote>

4. Your app should confirm that the user has a free trial version of the app. 
5. Your app should [identify the user](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/identify-and-manage-app-users.md) and enable access to features included in the free trial. 

### How to know if the user is in their free trial period
- **SDK/REST calls**: Call [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md).
     - Check if `isFree: false`, indicating that the user is currently a paying user.
     - Check for a billing object within the Get App Instance response data with detailed information about the user’s plan, which also contains `freeTrialInfo` and the trial status. Note that the `expirationDate` in the billing object will only be updated after the free trial is complete.
- **iFrame apps**: Check the [instance parameter](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/parse-the-app-instance-query-parameter.md) appended to your iframe URL when a user opens the app. The `vendorProductId` will be included. (This is the same whether the user has a free trial or paid plan.)

### Upgrade without a free trial

1. The user initiates purchase of a paid version of your app, or a plan that costs more than the one they already have, by clicking **Upgrade**, which brings them to the upgrade process.
2. When there is no free trial available, or the user decides to upgrade without a trial, the full amount is charged.
3. The user completes the purchase flow for the paid plan.

   <blockquote class="important">
  
   __Important:__ The [Paid Plan Purchased webhook](https://dev.wix.com/docs/rest/app-management/app-instance/paid-plan-purchased.md) is triggered when a user purchases a paid plan. 
   </blockquote>

4. Your app should confirm that the user has a paid version of the app. 
5. Your app should [identify the user](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/identify-and-manage-app-users.md) and enable access to the features included in the purchased plan. 

### How to know if the user has a paid plan
- **SDK/REST calls**: Call [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md).
     - Check if `isFree: false`, indicating that the user is currently a paying user.
     - Check if the `expirationDate` in the billing object is updated to reflect the current date of the charge plus 30 days (or 1 year if the plan is annual).
- **iFrame apps**: Check the [instance parameter](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/parse-the-app-instance-query-parameter.md) appended to your iframe URL when a user opens the app. The `vendorProductId` will be included. (This is the same whether the user has a free trial or paid plan.)


## Stage 3 | First billing cycle 

If the user signs up for a free trial and does not cancel before it ends, their first billing cycle begins, and they are charged for the plan.

### How to know if the user has completed their free trial and been charged
- **SDK/REST calls**: Call [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md).
     - Check if `isFree: false`, indicating that the user is currently a paying user.
     - Check if the `expirationDate` in the billing object is updated to reflect the current date of the charge plus 30 days (or 1 year if the plan is annual).
- **iFrame apps**: There is no indication that this change has occured. Check the [instance parameter](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/parse-the-app-instance-query-parameter.md) appended to your iframe URL when a user opens the app. The `vendorProductId` will be included. To confirm that the user no longer has a free trial, call [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md).

<blockquote class="important">
  
__Important:__  No event is triggered to indicate that a user has completed their free trial and been charged.
</blockquote>

## Stage 4 | Cancellation
Users can turn off the auto-renewal of the app's paid plan at any time. If you receive an event notifying you of an auto-renewal cancellation, take note that just because the auto-renewal is off, doesn't mean they aren't currently a paying customer. 

You can't downgrade the user until their subscription ends at the end of the month or year, depending on your app’s payment plan.

### How to know if the user canceled their free trial or paid plan 

If the user cancels their free trial or paid plan, the following occur:
- **Immediately**: The [Paid Plan Auto Renewal Cancelled webhook](https://dev.wix.com/docs/rest/app-management/app-instance/paid-plan-auto-renewal-cancelled.md) is triggered. Note that the user is still considered a paid user until the plan expires.
- **When the paid plan or free trial expires**:
    - **SDK/REST calls**: Call [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md). Once the user's plan or trial expires, their status reverts to `isFree: true`. 
    - **iFrame apps**: Check the [instance parameter](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/parse-the-app-instance-query-parameter.md). Once the user's plan or trial expires, `vendorProductId` is not returned.

If the returned expiration date has passed, but the `isFree` parameter in [Get App Instance](https://dev.wix.com/docs/rest/app-management/app-instance/get-app-instance.md) is still false - consider the user as a paid user. This means that the site owner has a billing issue. Once they either fix the issue or cancel their subscription, the date returned in the app instance data will update.

## Overview of key events

| **Event**  | **Webhook**     | **SDK/REST call to Get App Instance**        | **iFrame apps instance parameter**     |
|------------------|-----------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| **Installation**            | App installed event                     | `isFree: true` (user is on a free plan)                                                                                     | No `vendorProductId` in the instance parameter                                                                                                   |
| **Upgrade with free trial**  | Paid Plan Purchased event               | `isFree: false` (user is paying), billing object with `freeTrialInfo` and trial status, and no `expirationDate`      | `vendorProductId` included in the instance parameter                                                                                             |
| **Upgrade without free trial**              | Paid Plan Purchased event               | `isFree: false` (user is paying), `expirationDate` updated to reflect new charge (30 days or 1 year)                        | `vendorProductId` included in the instance parameter                                                                                             |
| **First billing cycle after transaction** | No event triggered                       | `isFree: false` (user is paying), `expirationDate` updated to reflect current date of charge plus 30 days (or 1 year for annual plans)         | `vendorProductId` included in the instance parameter                                                                                             |
| **Cancelled subscription**  | Paid Plan Auto Renewal Cancelled event  | `isFree: true` (user reverts to free plan)                                                                                  | No `vendorProductId` in the instance parameter