> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# App Store Deeplinks

> Build links that open your app's listing on Fanvue with a specific pricing plan preselected, or that skip straight to install/checkout.

App Store deeplinks are URLs you can share in marketing emails, in-app CTAs, support flows, or documentation that take a Fanvue user directly to your app's listing page. With one extra query parameter you can preselect a specific pricing plan in the install dialog. With one more, you can skip the dialog entirely and send the user straight into the install/checkout flow.

Use them when you want to drive a specific plan rather than the generic "open the app's listing" experience.

<Info>
  Deeplinks are stable, shareable URLs. You can hand them out in emails, embed
  them in your own site, or use them as CTAs from a partner integration, there
  is nothing to install on the recipient's side.
</Info>

## URL shape

The base of every App Store deeplink is your app's listing page:

```
https://www.fanvue.com/app-store/details/<appUuid>
```

That URL on its own opens the listing exactly as if a creator had browsed there. To turn it into a deeplink, add a `plan` query parameter (and optionally `action=checkout`).

| Parameter | Required                               | Allowed values                                | Effect                                                                                        |
| --------- | -------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `plan`    | Yes, to trigger any deeplink behaviour | The `uuid` of one of your app's pricing plans | Preselects that plan in the install dialog.                                                   |
| `action`  | No                                     | `checkout`                                    | Skips the plan picker and immediately starts the install/checkout flow for the selected plan. |

If `plan` is missing or empty, the page renders normally and `action` has no effect. `action=checkout` only makes sense in combination with a valid `plan`.

## The two canonical shapes

```bash theme={null}
# Open the listing with a plan preselected in the picker dialog
https://www.fanvue.com/app-store/details/<appUuid>?plan=<planUuid>

# Open the listing and go straight to install / checkout for that plan
https://www.fanvue.com/app-store/details/<appUuid>?plan=<planUuid>&action=checkout
```

Use the picker form when you want the user to see plan details before confirming. Use the `action=checkout` form when the user has already chosen, e.g. they clicked a plan-specific CTA in an email.

## Where to get your `planUuid`

Plan UUIDs are visible in the **Pricing** tab of your app in the Developer area. Each row in the pricing plans table has a **Plan ID** cell that shows a truncated UUID; click it to copy the full UUID to your clipboard, then paste it into your deeplink as the value of `plan`.

<Note>
  Only plans with an **Active** status can be deeplinked. Plans that are in
  setup, withdrawn, or otherwise inactive will trigger an error toast on the
  listing page if used as the target of a deeplink, see [Invalid or unusable
  plan](#invalid-or-unusable-plan) below.
</Note>

## Behaviour by viewer state

Because a deeplink can be opened by any Fanvue user, the resulting experience depends on the viewer's current relationship with your app. The matrix below summarises what each user sees.

| Viewer state                                              | `?plan=<planUuid>`                                                                  | `?plan=<planUuid>&action=checkout`                            |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Not installed, no subscription                            | Picker opens with the plan preselected                                              | Install / payment dialog opens immediately                    |
| Installed on a free plan, target is a paid plan (upgrade) | Picker opens in upgrade mode with the paid plan preselected (free plans are hidden) | Payment dialog opens immediately for the upgrade              |
| Already subscribed to the targeted paid plan              | No-op, listing renders normally                                                     | No-op, listing renders normally                               |
| Already has access and the target is a free plan          | No-op, listing renders normally                                                     | No-op, listing renders normally                               |
| Targeted plan doesn't exist on this app, or isn't active  | Error toast, listing renders normally                                               | Error toast, listing renders normally                         |
| Has an abandoned payment for the targeted plan            | Picker opens with the plan preselected                                              | The existing payment dialog is resumed (no duplicate invoice) |

A few of these are worth calling out explicitly.

### Already on the targeted plan

If the viewer already has access to the exact plan you're deeplinking to, either because they're actively subscribed to that paid plan, or they already have access and the target is a free plan, the deeplink is treated as a no-op and the listing renders as normal. This is safe to send to broad audiences: existing subscribers won't be pushed back through checkout.

### Upgrade mode

If the viewer already has access via a different paid or free plan and the deeplink targets a different paid plan, the picker opens in **upgrade mode**: free plans are hidden so the user can't downgrade by accident, and the targeted plan is preselected. The `action=checkout` form goes straight to the upgrade payment dialog.

### Pending / abandoned payment

If the viewer previously started checking out on the targeted plan and closed the dialog without completing payment, the deeplink will **resume the same payment** rather than creating a new one. Both forms behave the same way here, `action=checkout` reopens the existing payment dialog, and the plain `plan=` form preselects the plan so the user can reopen it themselves from the picker.

### Invalid or unusable plan

If the `plan` UUID doesn't belong to this app, or the plan exists but isn't active (for example, it has been withdrawn), the listing renders normally and the user sees an inline error toast indicating that the deeplink was invalid. Audit your outbound links if creators report seeing this, usually it means the plan was withdrawn after the link was sent.

## Choosing between the two forms

A simple rule of thumb:

* Use **`?plan=`** (picker form) when the user hasn't necessarily committed yet, for example, a "Choose your plan" CTA in an onboarding email where you want them to see plan details before paying.
* Use **`?plan=...&action=checkout`** when the CTA itself is plan-specific, for example, a "Upgrade to Pro" button on your marketing site where the choice has already been made.

Both forms are safe for users who are already subscribed: as shown above, the deeplink no-ops rather than triggering duplicate payments.

## Related reading

* **[App Store Introduction](/app-store/introduction)**, overview of the App Store and the build-to-publish journey.
* **[App Subscriptions](/app-store/app-subscriptions)**, read pricing lifecycle and current-user entitlement for an app via the API.
* **[App Types](/app-store/app-types)**, embedded vs off-platform apps and how pricing plans interact with each.