# Add deep links

Create deep links that navigate users to your Stripe app.

> Use deep links only for external links, such as emails or external websites. For links rendered within your Stripe app, use [route descriptors](https://docs.stripe.com/stripe-apps/route-descriptors.md) instead—they offer [several benefits](https://docs.stripe.com/stripe-apps/route-descriptors.md#benefits-of-route-descriptors) for in-app navigation.

A deep link is a URL that reduces the number of navigation steps required for the user to open your app in the Dashboard. Use deep links only in external contexts, such as an email or website, or when [creating OAuth authorization workflows](https://docs.stripe.com/stripe-apps/pkce-oauth-flow.md). To navigate between pages within your app, use [route descriptors](https://docs.stripe.com/stripe-apps/route-descriptors.md) instead.

## Before you begin

To navigate users to a Dashboard page that displays your app, you need an app with [UI functionality](https://docs.stripe.com/stripe-apps/build-ui.md).

## Create the deep link URL

The format of a deep link depends on the view you want to open. To open a drawer or modal over a Dashboard page, add the `apps` parameter to that page’s URL. To open a full-page view, use your app’s full-page URL.

### Drawer and modal views

The structure of the deep link URL is:

```
https://dashboard.stripe.com/<ACCOUNT_ID>/<MODE>/<PAGE>?apps[<APP_ID>][TARGET]=VIEWPORT_ID
```

Where:

- **ACCOUNT\_ID**: The Stripe account ID where your app is installed (starts with `acct_`), available from the [user context](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#user-context)
- **MODE**: Use `test` for *sandboxes* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) (including the *test mode sandbox* (Every Stripe account includes the test mode sandbox. It shares some settings with live mode, has characteristics that differ from other sandboxes you create, but you can't delete it)) or omit a value for live mode
- **PAGE**: A Dashboard page where you’ve defined a *view* (A view is a React component that creates UI extensions in the Stripe Dashboard) (such as `customers`, `invoices`, or `dashboard`)
- **APP\_ID**: Your application ID, from the `id` field of your [stripe-app.json](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema) manifest file
- **TARGET**: Where to open your app, such as `drawer` (if you use drawers) or `modal` (to open onboarding)
- **VIEWPORT\_ID**: Viewport IDs configured in your manifest file (such as `stripe.dashboard.payment.list`)

> A legacy format using the `open_drawer_app` parameter continues to work for backwards compatibility, but we recommend the `apps` parameter.

If you define a view on the Customers page in the Dashboard (`https://dashboard.stripe.com/test/customers?`) and your application ID is `com.example.my-app`:

- The deep link for any type of *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) is:

  ```
    <a href="https://dashboard.stripe.com/acct_id/test/customers?apps[com.example.my-app][drawer]=">Deep Link</a>
  ```

  All sandbox deep link URLs include `/test/`. It isn’t related to legacy test mode.

- The live mode deep link is:

  ```
  <a href="https://dashboard.stripe.com/acct_id/customers?apps[com.example.my-app][drawer]=">Deep Link</a>
  ```

You can open your app on any Dashboard page where you’ve defined a view. For example, to open on the Dashboard home:

```
 <a href="https://dashboard.stripe.com/acct_id/test/dashboard?apps[com.example.my-app][drawer]=">Deep Link</a>
```

To create a deep link to your onboarding modal, use `modal` instead of `drawer`:

```
<a href="https://dashboard.stripe.com/acct_id/dashboard?apps[com.example.my-app][modal]=">Open in Modal</a>
```

### Full-page views

To open your app’s [full-page view](https://docs.stripe.com/stripe-apps/patterns/full-page-apps.md), use its Dashboard URL.

The structure of a full-page app URL is:

```
https://dashboard.stripe.com/<ACCOUNT_ID>/<MODE>/app/<APP_ID>/<ROUTE>
```

Where:

- **ACCOUNT\_ID**: The Stripe account ID where your app is installed (starts with `acct_`)
- **MODE**: Use `test` for *sandboxes* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) (including the *test mode sandbox* (Every Stripe account includes the test mode sandbox. It shares some settings with live mode, has characteristics that differ from other sandboxes you create, but you can't delete it)) or omit a value for live mode
- **APP\_ID**: Your application ID, from the `id` field of your manifest file
- **ROUTE**: (Optional) A path that matches a route in your app’s [route config](https://docs.stripe.com/stripe-apps/routing.md#define-a-route-config), such as `customers/cus_123`. Omit it to open your app’s root route.

For example, if your application ID is `com.example.my-app` and your app defines a `/customers/:id` route:

- The live mode link to your full-page app’s root route is:

  ```
  <a href="https://dashboard.stripe.com/acct_id/app/com.example.my-app">Open app</a>
  ```

- The live mode link to a specific customer is:

  ```
  <a href="https://dashboard.stripe.com/acct_id/app/com.example.my-app/customers/cus_123">View customer</a>
  ```

- The sandbox link to the same customer is:

  ```
  <a href="https://dashboard.stripe.com/acct_id/test/app/com.example.my-app/customers/cus_123">View customer</a>
  ```

If you change a route path after you share links to it, add a [redirect](https://docs.stripe.com/stripe-apps/routing.md#handle-redirects) from the old path so existing deep links continue to work.

## Share the deep link

Make sure you use the live mode URL when you share the deep link with your users. You can share the link in any external channel, such as an email or website, for users who’ve installed your app. If the user hasn’t installed your app before clicking the deep link, a drawer or modal deep link takes them to a closed app that can’t open in the Dashboard. A full-page app link shows an error page that links to your app’s Stripe App Marketplace listing.

## Test the deep link

1. Log in to the Dashboard as a user who has installed the app.

2. Click the deep link.

   If your app doesn’t open, make sure that:

   - The URL uses the correct application ID from your manifest
   - The account ID in the URL path is correct (format: `acct_` followed by alphanumeric characters)
   - The user has the app installed for that account
   - The Dashboard page in the URL has a view defined for your app, or for full-page app links, your app defines a `stripe.dashboard.fullpage` [viewport](https://docs.stripe.com/stripe-apps/reference/viewports.md)

## See also

- [App manifest reference](https://docs.stripe.com/stripe-apps/reference/app-manifest.md)
- [Versions and releases](https://docs.stripe.com/stripe-apps/versions-and-releases.md)
- [Full-page apps](https://docs.stripe.com/stripe-apps/patterns/full-page-apps.md)
- [Routing](https://docs.stripe.com/stripe-apps/routing.md)