Dynamic Routes

Dynamic routes use a path parameter (:token) to create unique links. Instead of one fixed URL, you generate a different link for each user, product, session, or entity in your system.

How it works

When you create a dynamic route with the prefix pay, your links look like:

https://your-app.tolinku.com/pay/merchant-abc
https://your-app.tolinku.com/pay/merchant-xyz
https://your-app.tolinku.com/pay/coffee-shop-42

The part after the prefix is the token. You decide what it represents. When someone taps the link, the full URL is passed to your app so it can parse the token and navigate to the right screen.

Basic dynamic routes

In the simplest case, you create a dynamic route, share links with different tokens, and your app handles the rest. No server-side work is needed.

How it flows:

1. You share https://your-app.tolinku.com/join/room-abc
2. User taps the link on mobile
3. If the app is installed, it opens and receives the URL. Your app reads the token room-abc and navigates to the right screen.
4. If the app is not installed, the user sees a generic branded landing page with download buttons, then gets deep linked after installing (deferred deep linking).

The token travels through the entire funnel, from link tap to app open, even through an app install. This is called deferred deep linking: Tolinku remembers the original URL and token, so when the user finishes installing and opens the app for the first time, the SDK delivers the full link to your app. The user lands on the right screen, not the home screen.

Note

Deferred deep linking requires the Tolinku SDK in your app. Without the SDK, users who install the app will open to the home screen. The link itself (Universal Links / App Links) only works for users who already have the app.

When to use basic dynamic routes

Basic dynamic routes work best when the token only makes sense inside the app and the landing page doesn’t need to show personalized content. The generic landing page says “Download [Your App]” and that’s enough context.

Group or room invites: A link like /join/room-abc drops the user into a specific chat room, game lobby, or collaboration space. The token identifies the room; the landing page just needs to get them to the app.

Magic login links: /login/token-xyz authenticates the user and opens the app. There’s nothing meaningful to show on a landing page.

Activation or verification: /verify/code-123 confirms an email address or activates an account. The link does its job when the app opens.

In-app navigation shortcuts: /screen/settings or /screen/profile deep links users to a specific screen. Useful for push notification payloads or email CTAs where the user almost certainly has the app installed.

QR-based check-in: A venue prints QR codes with /checkin/event-456. Attendees scan and the app handles check-in. If they don’t have the app, the generic landing page prompts a download.

Example: Group invite flow

1. Alex creates a study group in your app
2. App generates: https://your-app.tolinku.com/join/study-group-alex
3. Alex shares the link in a group chat
4. Jamie taps the link
   - App installed? Opens directly to the study group
   - No app? Landing page -> App Store -> installs -> opens app
     -> SDK delivers the token -> app navigates to the study group
5. The token "study-group-alex" is preserved through the entire flow,
   including through the App Store install (deferred deep linking)

API-enriched dynamic routes

Basic dynamic routes show the same generic landing page for every token. With an API endpoint, the landing page becomes personalized: it shows content specific to each link, gives users immediate value, and can include web-based actions as a fallback.

This is where dynamic routes get powerful. The landing page is not just a “download our app” wall. It provides useful information and options, while nudging the user toward installing.

How it flows

1. A customer scans a QR code: https://your-app.tolinku.com/pay/coffee-shop-42
2. They don’t have the app installed
3. Tolinku calls your API: https://api.yourapp.com/merchant/coffee-shop-42
4. Your API returns the merchant name, logo, and a web payment URL
5. The landing page shows “Pay Coffee Shop” with two options:
   • Install the app to pay (and get rewards, receipts, etc.)
   • Pay on web (redirects to the merchant’s web payment page)
6. If they install, the app opens with the token coffee-shop-42 and goes straight to the payment screen

The key insight: the landing page provides immediate value even without the app, while making the app the better option.

Setting up the API endpoint

In the route form, expand Advanced Settings and enter your API URL. Use {token} as a placeholder:

https://api.yourapp.com/merchant/{token}

Tolinku replaces {token} with the actual token from the link before calling your endpoint.

API response format

Your endpoint should return JSON. The landing page template can use any fields you return:

{
  "title": "Coffee Shop Downtown",
  "description": "Scan to pay. Earn rewards with every purchase.",
  "image": "https://cdn.yourapp.com/merchants/coffee-shop-42/logo.png",
  "cta": "Pay with App",
  "fallback_url": "https://pay.coffeeshop.com/checkout"
}

Tip

The API endpoint is called server-side by Tolinku. It does not need to be accessible from the user’s browser. However, any image URLs in the response should be publicly accessible since the browser loads them directly.

Use cases for API-enriched routes

Merchant payments (QR at point of sale): Each merchant gets a QR code linking to /pay/merchant-id. Customers who scan it see the merchant name, logo, and payment options. They can install the app for the full experience or pay via a web fallback. Over time, the app install converts into a repeat customer.

Restaurant menus and ordering: A table tent has a QR code for /menu/downtown-cafe. The landing page shows the restaurant name, hours, and cuisine type. Options: “Open in App” (full menu with ordering) or “View Menu Online” (web fallback). The user gets value immediately; the app is the premium path.

Event tickets and check-in: /event/music-fest-2026 shows the event name, date, venue, and the user’s ticket details. Options: “Open in App” (barcode, schedule, maps) or “View Ticket” (web version). The landing page works as a standalone ticket while promoting the richer app experience.

Loyalty and rewards: /rewards/user-sarah shows Sarah’s points balance and available rewards. She can “Open in App” to redeem, or “View Rewards” on web. The personalized data (her actual balance) creates an incentive to engage.

Personalized invites: /invite/sarah-123 calls your API, which returns Sarah’s name and avatar. The landing page says “Sarah invited you to join FoodDash” with her profile picture, instead of a generic “You’ve been invited.” The personal touch increases conversion.

Real estate or property listings: /listing/123-main-st shows the property photo, price, and bedroom count. “View in App” gives the full listing with maps, tours, and agent contact. “View Online” goes to the web listing. The landing page acts as a teaser that earns the install.

Example: Merchant payment QR

Your route prefix is pay. API endpoint: https://api.yourapp.com/merchant/{token}

Customer scans QR at counter:
  https://your-app.tolinku.com/pay/coffee-shop-42

Tolinku calls: GET https://api.yourapp.com/merchant/coffee-shop-42

Your API returns:
{
  "title": "Coffee Shop Downtown",
  "image": "https://cdn.yourapp.com/merchants/coffee-shop.png",
  "description": "Tap to pay. Earn 2x rewards this week.",
  "cta": "Pay with App",
  "fallback_url": "https://pay.coffeeshop.com/checkout"
}

Landing page (user without app):
┌─────────────────────────────────┐
│  [Coffee Shop Logo]             │
│                                 │
│  Coffee Shop Downtown           │
│  Tap to pay. Earn 2x rewards.  │
│                                 │
│  [ Pay with App  ]  (primary)   │
│  [ Pay on Web    ]  (fallback)  │
│                                 │
│  Download on App Store          │
│  Get it on Google Play          │
└─────────────────────────────────┘

- "Pay with App" -> install flow -> app opens to payment screen
- "Pay on Web" -> redirects to pay.coffeeshop.com/checkout

The user is never stuck. They can complete their goal (paying) regardless of whether they install the app. But the app is positioned as the better option with rewards and a smoother experience. Over time, more users install.

Choosing between basic and API-enriched

Question	Basic	API-enriched
Does the landing page need to vary per link?	No, generic branding is fine	Yes, each link shows different content
Can the user do something useful without the app?	No, the value is inside the app	Yes, provide a web fallback or preview
Do you have a backend that can serve data?	Not required	Yes, you need an API endpoint
How fast do you need to launch?	Immediate, no server work	Requires API development

Start with basic dynamic routes. Add the API endpoint later when you want personalized landing pages. The deep linking behavior (app opening, deferred deep linking) works the same either way.

Generating dynamic links

There are several ways to create individual dynamic links:

1. Manually: Share the URL directly. If your prefix is pay and the token is coffee-shop-42, the URL is https://your-app.tolinku.com/pay/coffee-shop-42.

2. Via the API: Use the Tolinku REST API to generate links programmatically from your backend.

3. Via SDKs: The Tolinku SDKs provide methods to generate and share dynamic links from your app.

4. QR codes: Generate QR codes for any dynamic link. Print them on receipts, packaging, signage, or table tents.

Token guidelines

Tokens can be any URL-safe string. Keep these in mind:

• Use alphanumeric characters, hyphens, and underscores
• Avoid special characters that need URL encoding
• Keep tokens short for sharing (under 64 characters)
• Use unpredictable tokens (UUIDs, random strings) if the link grants access to sensitive content. Don’t use sequential IDs like user/1, user/2.