> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile apps

> Credit partners for in-app purchases. Users enter a partner's code or open a partner's app link, and RevenueCat sends the purchases.

Links and cookies don't survive an App Store install. In an app, attribution works on the user instead: the app claims the partner's code for its own user id, and every purchase RevenueCat reports for that user is credited to the partner.

Partner link/a/…/SAM20Your appTolt SDKRevenueCatpurchasesToltattribution*1*tolt\_click=clk\_7Rq2…*2*POST /client/claims*3*purchase*4*INITIAL\_PURCHASE*5*comm\_2nV8…

The user's app user id becomes the customer's `customer_id` in Tolt. Use the same id you give RevenueCat.

## Set up

**1. Connect RevenueCat**

Add the Tolt webhook to your RevenueCat project. See [RevenueCat](https://docs.tolt.com/integrations/revenuecat.md).

**2. Claim codes in your app**

Add the [Swift](https://docs.tolt.com/sdks/swift.md) or [Android](https://docs.tolt.com/sdks/android.md) SDK and claim the code when the user enters one, for example on a "Have a code?" screen.

```swift Swift theme={"system"}
import Tolt

Tolt.configure(publicId: "YOUR_PUBLIC_KEY")

let result = try await Tolt.claim(
  code: "SAM20",
  appUserId: Purchases.shared.appUserID
)
```

```kotlin Kotlin theme={"system"}
import com.tolt.Tolt

Tolt.configure(context, publicId = "YOUR_PUBLIC_KEY")

val result = Tolt.claim(
  code = "SAM20",
  appUserId = Purchases.sharedInstance.appUserID
)
```

Your public key is under **Settings → Integrations** in the dashboard. On another platform, call [the claim endpoint](#claim-from-other-platforms) directly.

**3. Give partners app links (optional)**

Partners can share a link instead of a code. Set where it goes under **Program settings → Tracking → App links**, then copy each partner's link from their page in the dashboard. See [Partner app links](#partner-app-links).

**4. Test it**

Claim a partner's code as a test user, then find the customer under **Customers** in the dashboard. It shows as a lead until RevenueCat reports a purchase.

## Claim rules

* **First code wins.** Once a user has a partner, later claims return `already_claimed` and change nothing.
* **Claim window.** Set **Program settings → Tracking → Code claim window** to limit claims to the first days after a user first opens your app. The SDK records the first open for you. Leave it empty for no limit.
* **Matching.** Codes match without case, so `sam20` claims `SAM20`. The code and its partner must both be active.
* **One partner per code.** If two partners have the same code, the claim fails with `409`. Codes created in the dashboard are unique across your programs.

## Partner app links

Each partner code has an app link:

```text theme={"system"}
https://platform.tolt.com/a/YOUR_PUBLIC_KEY/SAM20
```

Opening it records a click for the partner, then sends the user on. Link previews from Slack, iMessage and other apps aren't counted as clicks.

| Your settings | Where the link goes |
| - | - |
| **Deep link template** set | The template, with `{code}` and `{click_id}` filled in |
| No template, **Google Play URL** set, Android device | Google Play, with the code and click in the install referrer |
| Anything else | A page that shows the code, a copy button and your store buttons |

The template is usually a link from your deep linking provider, which installs the app and then opens it with the values, or a link your app already handles:

```text theme={"system"}
https://yourapp.onelink.me/AbCd?deep_link_value={code}&deep_link_sub1={click_id}
myapp://claim?tolt_code={code}&tolt_click={click_id}
```

Claim the click when your app opens. A click claim credits the partner the same way a code does, and also ties the customer to the click.

> [tab] Your own link
>
> Pass a link with `tolt_click` or `tolt_code` straight to the SDK. It returns `nil` (`null` on Android) for links without either.
>
> ```swift Swift theme={"system"}
> .onOpenURL { url in
>   Task {
>     _ = try await Tolt.claim(
>       url: url,
>       appUserId: Purchases.shared.appUserID
>     )
>   }
> }
> ```
>
> ```kotlin Kotlin theme={"system"}
> override fun onNewIntent(intent: Intent) {
>   super.onNewIntent(intent)
>   val uri = intent.data ?: return
>   lifecycleScope.launch {
>     Tolt.claim(uri, appUserId = Purchases.sharedInstance.appUserID)
>   }
> }
> ```

> [tab] Deep linking provider
>
> Read the values from your provider's deep link callback and claim the click, or the code when there is no click.
>
> ```swift Swift theme={"system"}
> _ = try await Tolt.claim(
>   clickId: clickId,
>   appUserId: Purchases.shared.appUserID
> )
> ```
>
> ```kotlin Kotlin theme={"system"}
> Tolt.claimClick(
>   clickId = clickId,
>   appUserId = Purchases.sharedInstance.appUserID
> )
> ```

> [tab] Google Play
>
> Claim the install referrer when the app starts. The [Android SDK](https://docs.tolt.com/sdks/android.md) reads it once per install and claims the click in it.
>
> ```kotlin Kotlin theme={"system"}
> lifecycleScope.launch {
>   Tolt.claimFromInstallReferrer(
>     appUserId = Purchases.sharedInstance.appUserID
>   )
> }
> ```
>
> Without the SDK, read it with the Play Install Referrer library. It looks like `tolt_code=SAM20&tolt_click=clk_7Rq2…`. Send `tolt_click` as `click_id` to [the claim endpoint](#claim-from-other-platforms).

## Claim from other platforms

React Native, Flutter and other apps call the endpoint the SDKs use. It needs no API key, only your public key, so it's safe to call from the app.

```bash cURL theme={"system"}
curl -X POST https://platform.tolt.com/client/claims \
  -H "Content-Type: application/json" \
  -d '{
    "public_id": "YOUR_PUBLIC_KEY",
    "app_user_id": "user_8f2k",
    "code": "SAM20",
    "first_seen_at": "2026-11-04T09:30:00Z"
  }'
```

| Field | Description |
| - | - |
| `public_id` | Your public key. Required. |
| `app_user_id` | Your id for the user, the same one RevenueCat uses. Required. |
| `code` | The partner's code. Send this or `click_id`. |
| `click_id` | The click from an app link (`tolt_click`). Used instead of `code`. |
| `first_seen_at` | When the user first opened the app, as ISO 8601. Needed for the claim window. |

A successful claim returns `200`:

```json theme={"system"}
{
  "success": true,
  "message": "Success",
  "data": { "status": "claimed", "app_user_id": "user_8f2k" }
}
```

`status` is `claimed`, or `already_claimed` when the user already had a partner. Errors use the [usual error format](https://docs.tolt.com/api-reference/errors.md): `404` for an unknown public key, code or click, `409` when the code belongs to two partners or the claim window has closed, `400` for invalid input, and `429` above 30 requests a minute from one IP.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.