Configure redemption links in React Native
A customer who buys a subscription on the web should not have to hunt for a login screen when they return to your app. Redemption links are designed to make that handoff a single tap: the customer opens a deep link, the mobile SDK reads the URL, and the purchase is attached to that user so entitlements can unlock. This guide walks through the dashboard setting, the two common Expo integration paths, and how to prove the whole chain works. The behavior described here reflects the vendor's documented contract, not an independently tested result.
How a redemption link reaches your app
The flow has four moving parts. First, a customer finishes a Web Billing checkout, either through the Web SDK or a hosted Web Purchase Link. Second, the billing platform issues a one-time-use redemption link. Third, the customer taps that link on a device where your app is installed, and the operating system routes the URL to your app via the custom URL scheme. Fourth, the mobile SDK parses the URL parameters and associates the purchase with the customer.
Two properties make this pattern flexible. The checkout can be anonymous, so you do not need to know the App User ID at purchase time. And because the link is the claim mechanism, the same pattern serves win-backs, gifting, and cross-platform upgrades.
Before you start, confirm that products exist and Web Billing is enabled in the billing dashboard. The rest of this guide assumes that groundwork is done.
Step 1: Turn on redemption links and copy the scheme
In the billing dashboard, open your project and go to the Web tab. Inside the Web configuration section, open Redemption links and enable them for the environments you need. Then copy the Custom URL Scheme shown there; you will paste it into your Expo config in the next step. The scheme is the value that makes the deep link land in your app rather than a browser.
Step 2: Pick the integration that matches your navigator
The right handler depends on how your app already routes URLs. Use the table below as a quick decision aid.
| Your app uses | Recommended handler | Where the logic lives |
|---|---|---|
| React Navigation or another non-Expo-Router navigator | Expo Linking | A component that subscribes to incoming URLs |
| Expo Router | +native-intent.tsx with redirectSystemPath | A global native-intent interceptor |
Both paths call the same two SDK methods: parse the URL, then redeem it. The difference is only where you hook into the incoming URL.
Option A: Handle redemption links with Expo Linking
Expo's Linking API is the hook that lets a React Native app react to URLs arriving from outside it. It supports custom schemes and Universal Links/App Links; this walkthrough sticks to a custom scheme because it is the simplest to reason about.
First, register the scheme. If you already have a scheme in app.json, keep it and add the redemption scheme as a second entry so the two do not collide. On iOS, add both schemes under ios.infoPlist.CFBundleURLTypes. The exact app.json snippet is provided in protected module code0001.
After editing, run npx expo prebuild to regenerate the ios folder. To confirm the schemes registered, open Xcode and check Target → Info → URL Types; both your existing scheme and the redemption scheme should be listed.
On Android, the equivalent field is android.intentFilters. The exact snippet is in protected module code0002. If you are not on Expo, the React Navigation deep-linking guide covers the native configuration for bare React Native projects.
With the schemes in place, add the listener. The component subscribes to Linking.useURL(), and whenever a URL arrives it calls Purchases.parseAsWebPurchaseRedemption(url) and, if a redemption object comes back, Purchases.redeemWebPurchase(redemption). The exact implementation is in protected module code0003.
Option B: Handle redemption links with Expo Router
If your app is on Expo Router, you do not need a custom listener or a dedicated route. Instead, create +native-intent.tsx and export a redirectSystemPath function. Expo Router calls it for every incoming native intent, so you can parse the URL, attempt the redemption, and then return the path the user should land on.
The pattern is: parse with Purchases.parseAsWebPurchaseRedemption(path), redeem with Purchases.redeemWebPurchase(webPurchaseRedemption) when a redemption object is returned, log the result, and return a destination such as /(tabs). Wrap the body in a try/catch so a malformed URL still lands the user somewhere sensible. The exact implementation is in protected module code0004.
If you want the customer to see a confirmation, return a custom route instead of the main tabs, and render a success or failure screen there.
Step 3: Prove the flow end to end
You can exercise the deep link without a real purchase by opening a URL that matches your scheme. The command in protected module code0005 uses npx uri-scheme open with the sample scheme and a placeholder redemption_token. If the wiring is correct, the app opens and logs whether the redemption succeeded or failed; a placeholder token will fail, which is the expected signal that the handler ran.
For a realistic test, the vendor documents that you can complete a sandbox web purchase, send yourself the resulting redemption link, and open it on a device with your app installed; the app should open and the subscription should redeem. Treat that as the documented expectation to verify in your own environment, not as a result this guide has executed. After that, the remaining work is UX: a custom screen that congratulates the customer on starting their premium subscription is a good finishing touch.
For the checkout side, you can embed the Web SDK or use Web Purchase Links to host a paywall with minimal code. Both feed the same redemption-link pattern.
Pre-launch checklist
- [ ] Web Billing is enabled and products exist in the billing dashboard.
- [ ] Redemption links are enabled for the environments you will test and ship.
- [ ] The Custom URL Scheme from the dashboard is present in
app.jsonalongside any existing scheme. - [ ]
npx expo prebuildhas been run and Xcode shows both schemes under URL Types. - [ ] Android
intentFiltersinclude both schemes withBROWSABLEandDEFAULTcategories. - [ ] The Expo Linking listener or the Expo Router
redirectSystemPathhandler is wired to parse and redeem. - [ ] A placeholder-token test opens the app and logs a redemption attempt.
- [ ] A sandbox web purchase redeems successfully on a device.
- [ ] A success/failure screen or toast is in place for the customer.
Telling failures apart
When a redemption does not work, the symptom usually points at one of three layers.
The link does not open the app. The scheme is missing or misconfigured. Re-check app.json, rerun npx expo prebuild, and confirm the scheme appears in Xcode's URL Types and in the Android intent filters.
The app opens but nothing is logged. The listener is not mounted, or the URL is not reaching it. On Expo Linking, confirm Linking.useURL() is inside a component that is actually rendered. On Expo Router, confirm the file is named +native-intent.tsx and the export is redirectSystemPath.
The handler runs but the redemption fails. The token is invalid, expired, or already used. Redemption links are one-time-use, so a link that worked once will not work again. Use a fresh sandbox purchase to retest.
Config field map
| Platform | app.json path | What goes there |
|---|---|---|
| iOS | ios.infoPlist.CFBundleURLTypes | One entry per scheme, each with a CFBundleURLSchemes array |
| Android | android.intentFilters | A VIEW action with data entries per scheme and BROWSABLE/DEFAULT categories |
The exact snippets are in protected modules code0001 and code0002.
Frequently asked questions
Do I need to pass an App User ID when the customer buys on the web?
No. The checkout can be anonymous. The redemption link is what ties the purchase to the customer's App User ID when they open it on their device.
Can the same redemption link be used more than once?
No. The billing platform issues a one-time-use link. If a link has already been redeemed, you will need a fresh purchase to generate a new one.
Which handler should I use, Expo Linking or Expo Router?
Use Expo Linking if your app is on React Navigation or another non-Expo-Router navigator. Use Expo Router's +native-intent.tsx with redirectSystemPath if your app is on Expo Router.
How do I test without a real purchase?
Run the npx uri-scheme open command from protected module code0005 with a placeholder token. The app should open and log a redemption attempt; a placeholder token will fail, which confirms the handler is wired. For a full test, use a sandbox web purchase.