# 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

To create the URL of the deep link, you must use:

- The Stripe account ID where your app is installed. See [User context](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#user-context) for more details.
- The URL of a Dashboard page where you’ve defined a *view* (A view is a React component that creates UI extensions in the Stripe Dashboard).
- The `apps` parameter to specify your app and where to open it.
- Your application ID, which is specified in the [`id` field of your `stripe-app.json` manifest file](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema).

> A legacy format using the `open_drawer_app` parameter continues to work for backwards compatibility, but the modern `apps` parameter format is recommended.

### Deep link format

The structure of a 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 (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
- **PAGE**: The Dashboard page to display (such as `customers`, `invoices`, or `dashboard`)
- **APP\_ID**: Your application ID from your 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`)

### Examples

If you define a *view* (A view is a React component that creates UI extensions in the Stripe Dashboard) on the Customers page in the Dashboard (`https://dashboard.stripe.com/test/customers?`) and your application ID is `com.example.my-app`:

- The *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) or test mode sandbox deep link is:

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

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

## 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, Stripe navigates them to a closed app that can’t open in the Dashboard.

## Test the deep link

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

2. Click the deep link.

   If it navigates you to an app that can’t open, make sure that:

   - The `apps` parameter 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

## 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)