Add deep links

Create deep links that navigate users to your Stripe app.

Caution

Use deep links only for external links, such as emails or external websites. For links rendered within your Stripe app, use route descriptors instead—they offer several benefits 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. To navigate between pages within your app, use route descriptors instead.

Before you begin

To navigate users to a Dashboard page that displays your app, you need an app with UI functionality.

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 for more details.
The URL of a Dashboard page where you’ve defined a view .
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.

Note

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:

the related setting : The Stripe account ID (starts with acct _ )
the related setting : Use test for sandboxes (including the test mode sandbox ) or omit a value for live mode
the related setting : The Dashboard page to display (such as customers , invoices , or dashboard )
the related setting : Your application ID from your manifest file
the related setting : Where to open your app, such as drawer (if you use drawers) or modal (to open onboarding)
the related setting : Viewport IDs configured in your manifest file (such as stripe. dashboard. payment. list )

Examples

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 sandbox 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:

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

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

Log in to the Dashboard as a user who has installed the app.
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