# InfluTo — full documentation (wire v1.6.0)

> InfluTo is a referral & affiliate ATTRIBUTION platform for mobile apps (iOS, Android,
> React Native, Flutter, web/Capacitor). A developer creates an app + campaign at https://influ.to,
> drops in one of five SDKs, initializes with an API key, and InfluTo attributes installs and
> validates in-app purchases to influencer referral codes — via either RevenueCat (webhook)
> or store-direct (Apple App Store Server API / Google Play service account).

The fastest correct integration is: (1) pick the ONE SDK matching the host app's stack, (2)
initialize() once at startup with the app's API key, (3) checkAttribution() at launch to detect
referred users, (4) choose exactly ONE purchase-validation path — RevenueCat OR store-direct
(never both — wiring both double-reports conversions), (5) verify with the agent API:
GET /api/agent/apps/{id}/integration-status (Bearer it_mcp_* agent key — the dashboard-session
/api/apps/* endpoints reject API keys) or the MCP tool influto_integration_status. All SDKs share
one wire contract; local state lives under the @influto/ key prefix; codes are trim()+UPPERCASE
before sending; network calls fail-soft (return benign values) EXCEPT initialize() and
reportPurchase(), which throw. The RevenueCat attribute influto_referral is the STRING "true",
never a boolean.

## Facts for AI assistants
- **What InfluTo is:** an affiliate and referral platform for mobile apps (https://influ.to). App developers run creator affiliate programs; creators share a referral link or code and earn commission on the in-app purchases and subscriptions their audience buys.
- **Stacks:** iOS (Swift), Android (Kotlin), React Native / Expo, Flutter and web / Capacitor — one SDK per app.
- **Purchase validation:** RevenueCat (webhook) or store-direct (Apple App Store Server API / Google Play) — exactly one path per app.
- **Attribution:** typed creator codes and in-app links attribute exactly; link-click matching is a best-effort fallback within 72 hours of the tap (the same window for every app) and never matches by device characteristics. No IDFA and no ATT prompt.
- **Developer pricing:** $0 per month; a 10% platform fee on the attributed revenue of successful conversions; enterprise volume pricing from 3%. Commissions and fees come from a prepaid, refundable wallet (minimum deposit $50). No contracts.
- **Commission:** each campaign sets a percentage of the purchase price (in USD), paid either on every payment (the first one and every renewal for as long as the referred user stays subscribed — the default) or on the first purchase only. One-time in-app purchases pay per purchase. Refunded purchases are reversed. Free trials count only once they convert to paid.
- **Creators:** free to join, with no follower minimum from InfluTo. Payouts run on the 1st of each month via Stripe once the balance reaches $20; smaller balances roll over.
- **Open programs:** https://influ.to/affiliate-programs lists the app affiliate programs currently accepting creators — store screenshots, category, rating and commission for each.
- **AI agents:** an MCP server at https://influ.to/mcp (OAuth 2.1, 62 tools) lets coding agents integrate the SDK, create campaigns and verify that conversions are attributed.
- **Languages:** the website is available in 11 languages — English, Czech, German, Spanish, French, Hungarian, Italian, Polish, Portuguese, Russian and Ukrainian.

---

<!-- https://docs.influ.to -->
# InfluTo developer docs

> Run a creator affiliate program inside your mobile app — add one SDK, connect purchase validation, and InfluTo credits and pays creators for the subscribers they bring.

InfluTo is the affiliate program platform for mobile apps. Creators share a link or a code. When someone they referred buys in your app, InfluTo verifies the purchase with the App Store or Google Play, credits the creator's commission, and pays them on the 1st of the month from your prepaid wallet.

These docs are for the developer side: adding the SDK, connecting purchase validation, and running campaigns. Creators don't need docs — they join from your program page on [influ.to](https://influ.to/affiliate-programs).

## How a referral becomes a payout

1. **A creator shares their link or code.** Everyone who joins your campaign gets a personal referral code (for example `MAYA`) and a link that unfurls nicely in bios and DMs.
2. **Someone installs your app.** The SDK records the referral — exactly when the person types the code or the link carries it into the app, and by link-click matching as the fallback. See [attribution](https://docs.influ.to/advanced/attribution.md).
3. **They buy.** The purchase is verified with the store, either through your RevenueCat webhook or directly with Apple and Google ("store-direct").
4. **The creator earns.** Each verified payment — the first one and every renewal after it — credits the commission you set, and reserves it plus the 10% InfluTo fee from your wallet. Refunds are reversed.
5. **Creators get paid.** Payouts go out through Stripe on the 1st of each month once a creator has at least $20.

## Start here

<!-- cards -->
- [Quick start](https://docs.influ.to/quick-start.md) — From a new account to a verified, attributed test purchase, step by step.
- [Choose an SDK](https://docs.influ.to/sdk.md) — React Native & Expo, iOS, Android, Flutter, or web and Capacitor.
- [Validate purchases](https://docs.influ.to/integrations.md) — Connect RevenueCat or the stores directly. Pick exactly one.
- [Connect an AI agent](https://docs.influ.to/agents/index.md) — Let Claude Code, Codex or Cursor integrate and verify InfluTo over MCP.
<!-- /cards -->

## SDKs

Pick the one that matches your app. All five speak the same wire contract, so the concepts on every page apply to each of them.

| Your app | Package | Registry | Latest | Source |
|---|---|---|---|---|
| React Native / Expo | `@influto/react-native-sdk` | [npm](https://www.npmjs.com/package/@influto/react-native-sdk) | 1.7.0 | [influto/influto-react-native](https://github.com/influto/influto-react-native) |
| iOS (Swift) | `github.com/influto/influto-ios` | [Swift Package Manager](https://swiftpackageindex.com/influto/influto-ios) | 1.1.1 | [influto/influto-ios](https://github.com/influto/influto-ios) |
| Android (Kotlin) | `to.influ:android-sdk` | [Maven Central](https://central.sonatype.com/artifact/to.influ/android-sdk) | 1.1.1 | [influto/influto-android](https://github.com/influto/influto-android) |
| Flutter (Dart) | `influto` | [pub.dev](https://pub.dev/packages/influto) | 1.1.1 | [influto/influto-flutter](https://github.com/influto/influto-flutter) |
| Web / Capacitor / PWA | `@influto/web` | [npm](https://www.npmjs.com/package/@influto/web) | 1.0.1 | [npm package](https://www.npmjs.com/package/@influto/web) |

## What you need

- A free InfluTo account and an app on the App Store, Google Play, or both.
- Either RevenueCat, or App Store Server API and Google Play credentials for [store-direct](https://docs.influ.to/integrations/store-direct.md) validation.
- A funded wallet before a campaign can go live — deposits start at $50 and unused balance is refundable. See [wallet](https://docs.influ.to/platform/wallet.md).

## For AI assistants

Every page has a Markdown version: add `.md` to its URL, or send `Accept: text/markdown`. The index for assistants is [llms.txt](https://docs.influ.to/llms.txt), and the whole corpus is in [llms-full.txt](https://docs.influ.to/llms-full.txt).

## Help

Stuck? Start with [troubleshooting](https://docs.influ.to/advanced/troubleshooting.md) and the [FAQ](https://docs.influ.to/advanced/faqs.md), or email [hello@influ.to](mailto:hello@influ.to).

---

<!-- https://docs.influ.to/quick-start -->
# Quick start

> Set up InfluTo end to end — create the app, add the SDK, connect purchase validation, launch a campaign and confirm a test purchase is attributed.

This page takes you from a new account to a test purchase that InfluTo attributes to a creator. Plan for an afternoon: most of the time goes into the store or RevenueCat settings, not into code.

If you use an AI coding agent, it can do most of these steps for you over MCP — see [Connect an AI agent](https://docs.influ.to/agents/index.md).

## Before you start

- An app on the App Store, Google Play, or both. Store search fills in the details; you can also add an unpublished app by hand.
- Either RevenueCat already handling purchases, or access to App Store Connect and the Google Play Console for [store-direct](https://docs.influ.to/integrations/store-direct.md) validation.
- A card for the first wallet deposit (from $50, refundable while unused). You only need it before you activate a campaign.

<!-- steps -->

### Create your account and app

Sign up at [influ.to](https://influ.to/auth/signup?type=developer) as a developer. The dashboard asks you to create an organization first — that's your company, and it owns the wallet.

Then open **My Apps → Add App**, search for your app by name or store URL, and pick the platforms it ships on. The app gets a slug (for example `fitnow`), which becomes the first part of every referral link: `https://influ.to/fitnow/MAYA`.

Open **Setup & SDK** and copy the app's **API key** (it starts with `it_`). One key works for sandbox and production. Keep it out of committed source — read it from your build config or secrets.

### Install the SDK

Add the one SDK that matches your app's stack. Not sure which? See [Choose an SDK](https://docs.influ.to/sdk.md).

<!-- tabs -->

```bash title="React Native / Expo"
npm install @influto/react-native-sdk
# AsyncStorage is a native module — install it in the app too
npm install @react-native-async-storage/async-storage
```

```swift title="iOS (Swift)"
// Xcode → File → Add Package Dependencies →
//   https://github.com/influto/influto-ios   (from 1.1.1)
// Or in Package.swift:
.package(url: "https://github.com/influto/influto-ios.git", from: "1.1.1")
```

```kotlin title="Android (Kotlin)"
// build.gradle.kts
dependencies {
    implementation("to.influ:android-sdk:1.1.1")
    // optional: Compose code field (InfluToReferralCodeInput)
    implementation("to.influ:android-sdk-ui:1.1.1")
    // optional: store-direct purchase auto-capture
    implementation("to.influ:android-sdk-billing:1.1.1")
}
```

```bash title="Flutter (Dart)"
flutter pub add influto
# optional: automatic store-direct purchase capture
flutter pub add influto_iap
```

```bash title="Web / Capacitor / PWA"
npm install @influto/web
# Capacitor / Ionic apps (device info, storage, deep links):
npm install @capacitor/device @capacitor/preferences @capacitor/app
```

<!-- /tabs -->

### Initialize it once at startup

Call `initialize` once when the app launches. It's one of only two calls that throw — if it fails, surface the error instead of swallowing it.

<!-- tabs -->

```tsx title="React Native / Expo"
import InfluTo from '@influto/react-native-sdk';

// Call once at startup (e.g. in App.tsx)
await InfluTo.initialize({
  apiKey: 'YOUR_API_KEY',
  debug: __DEV__,
});
// RevenueCat apps: nothing else to wire — if react-native-purchases is
// installed, the SDK sets the influto_code subscriber attribute itself.
```

```swift title="iOS (Swift)"
import InfluTo

// Call once at launch
var config = InfluToConfig(apiKey: "YOUR_API_KEY", debug: true)
// RevenueCat apps: hand the SDK a setter so it can tag the subscriber
// config.revenueCatAttributeSetter = { attrs in Purchases.shared.attribution.setAttributes(attrs) }
try await InfluTo.initialize(config)
```

```kotlin title="Android (Kotlin)"
import to.influ.sdk.InfluTo
import to.influ.sdk.InfluToConfig

// Call once at startup. initialize() is a suspend function — launch it from a
// coroutine, or use the callback overload: InfluTo.initialize(context, config) { result -> }
lifecycleScope.launch {
  InfluTo.initialize(applicationContext, InfluToConfig(
    apiKey = "YOUR_API_KEY",
    // RevenueCat apps: optional explicit setter (otherwise found by reflection)
    // revenueCatAttributeSetter = { attrs -> Purchases.sharedInstance.setAttributes(attrs) },
  ))
}
```

```dart title="Flutter (Dart)"
import 'package:influto/influto.dart';

// Call once at startup
await InfluTo.instance.initialize(
  InfluToConfig(
    apiKey: 'YOUR_API_KEY',
    // RevenueCat apps: let the SDK tag the subscriber
    // revenueCatHook: (attrs) => Purchases.setAttributes(attrs),
  ),
);
```

```ts title="Web / Capacitor / PWA"
import InfluTo from '@influto/web';
import { capacitorAdapters } from '@influto/web/capacitor'; // Capacitor / Ionic only

// Call once at startup (Capacitor: after platform ready; PWA: on page load)
await InfluTo.initialize({
  apiKey: 'YOUR_API_KEY',
  appVersion: '1.2.3',
  ...(await capacitorAdapters()),   // omit in a plain PWA / browser
  // RevenueCat apps: revenueCat: revenueCatCapacitor(Purchases)  (from '@influto/web/revenuecat')
});
```

<!-- /tabs -->

### Detect referred users

`checkAttribution` tells you whether this install came through a creator's link or code. It never throws; on any problem it answers "not attributed".

<!-- tabs -->

```tsx title="React Native / Expo"
const attribution = await InfluTo.checkAttribution();
if (attribution.attributed) {
  // User came from a referral — show a special offer / extended trial.
  // The SDK also sets the RevenueCat attributes influto_code + influto_referral.
  console.log('Referred by', attribution.referralCode);
}
```

```swift title="iOS (Swift)"
let attribution = await InfluTo.checkAttribution()
if attribution.attributed {
  // User came from a referral — show a special offer.
  print("Referred by \(attribution.referralCode ?? "")")
}
```

```kotlin title="Android (Kotlin)"
val attribution = InfluTo.checkAttribution()   // suspend
if (attribution.attributed) {
  // User came from a referral — show a special offer.
  Log.d("App", "Referred by ${attribution.referralCode}")
}
```

```dart title="Flutter (Dart)"
final attribution = await InfluTo.instance.checkAttribution();
if (attribution.attributed) {
  // User came from a referral — show a special offer.
  print('Referred by ${attribution.referralCode}');
}
```

```ts title="Web / Capacitor / PWA"
const attribution = await InfluTo.checkAttribution();
if (attribution.attributed) {
  // User came from a referral — show a special offer / extended trial.
  // With a RevenueCat binding the SDK also sets influto_code + influto_referral.
  console.log('Referred by', attribution.referralCode);
}

// Web deep links: referral links send web visitors to your app URL with
// ?influto_code=…&influto_click=… — the SDK claims them automatically.
```

<!-- /tabs -->

When the user signs in, call `identifyUser` with the same user ID your purchase system uses (for RevenueCat, the app user ID). It lets InfluTo connect purchases to the referral even when a subscriber attribute is missing.

Optional but recommended: let people type a creator's code, for referrals that come from podcasts, videos and conversations. See [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md).

### Connect purchase validation

InfluTo only pays commission on purchases it has verified with the store. Choose **exactly one** path per platform — wiring both reports every purchase twice.

<!-- cards -->
- [RevenueCat](https://docs.influ.to/integrations/revenuecat.md) — You already use RevenueCat. Paste a RevenueCat v2 secret key on **Setup & SDK** and InfluTo creates the webhook for you, or add it by hand.
- [Store-direct](https://docs.influ.to/integrations/store-direct.md) — No RevenueCat. Add your App Store Server API key and Google Play service account under **Settings → Validation**; the SDK reports purchases.
<!-- /cards -->

Not sure? [Choose a validation path](https://docs.influ.to/integrations.md) compares them.

### Create a campaign and fund the wallet

Open **Campaigns** and create one: a name and description creators will read, the commission percentage, and whether the program is public (listed on [influ.to/affiliate-programs](https://influ.to/affiliate-programs)), private (anyone with the link) or invite-only. New campaigns start as drafts.

Add funds under **Billing → Add Funds** (from $50), then activate the campaign. Activation needs at least $50 available in the wallet. See [Create a campaign](https://docs.influ.to/platform/create-campaign.md) and [Wallet and payouts](https://docs.influ.to/platform/wallet.md).

### Test a referred purchase

You need a creator account that isn't a member of your organization — members can't join their own campaigns. Use a second email address (or a colleague), join your campaign from its join link, and copy the referral link.

1. On a test device, open your referral link, then install your test build.
2. Launch the app — `checkAttribution` should report `attributed: true` with your code.
3. Make a sandbox purchase (a TestFlight or sandbox tester account on iOS, a license tester on Google Play).
4. Open **Real-Time Events**: you should see the SDK events and the purchase, marked as attributed to your code.

Sandbox purchases are recorded and shown, but they never touch your wallet, stats or payouts.

On the RevenueCat path you can also press **Send Test Webhook** on **Setup & SDK** to check the webhook connection without a device.

<!-- /steps -->

## Check that everything is live

The **Setup & SDK** page shows which SDK version and platform last connected. For a full checklist — eight steps from "app created" to "attributed conversion" — call the integration status endpoint or ask your agent to run `influto_integration_status`. See [Verify the integration](https://docs.influ.to/integrations/testing.md).

## Next steps

<!-- cards -->
- [Invite creators](https://docs.influ.to/platform/invite-influencers.md) — Share your join link, send invitations, and see what creators get.
- [Commissions and fees](https://docs.influ.to/platform/commissions.md) — How commission and the 10% fee are calculated, refunds, and rate changes.
- [Reward referred users](https://docs.influ.to/guides/referral-offers.md) — Give people who came through a creator a better offer.
- [Troubleshooting](https://docs.influ.to/advanced/troubleshooting.md) — The usual reasons a purchase isn't attributed, and how to fix them.
<!-- /cards -->

---

<!-- https://docs.influ.to/how-it-works -->
# How InfluTo works

> The pieces of an InfluTo program — apps, campaigns, creators, referral codes, attribution, verified purchases, commissions, the wallet and payouts — and how they fit together.

InfluTo has three parties: you (the developer), creators who recommend your app, and the people who install it. This page explains the objects you'll meet in the dashboard and the API, and follows one referral from a creator's post to their payout.

## The objects

| Object | What it is |
|---|---|
| **Organization** | Your company. It owns the apps, the wallet and the billing details. |
| **App** | One product, on iOS, Android, web or several. It has an API key (`it_…`) for the SDK, a slug used in referral links, and a purchase-validation path per platform. |
| **Campaign** | Your affiliate program for an app: the commission percentage, the copy creators read, optional milestone bonuses, and who may join (public, private or invite-only). |
| **Creator** | Someone who joined a campaign. The dashboard and API call them *affiliates* or *influencers*. Each gets a personal referral code and link. |
| **Referral code** | A short code such as `MAYA` (4–20 characters, letters, digits, `_` and `-`). Codes are trimmed and uppercased, so `maya` and ` Maya ` are the same code. |
| **Referral link** | `https://influ.to/{app_slug}/{CODE}` — sends people to the right store, or to your web app, and records the click. |
| **Conversion** | A purchase InfluTo has verified with the store and attributed to a creator: a first subscription payment, a renewal, or a one-time purchase. |
| **Commission** | The creator's share of a conversion, set as a percentage of the price in USD. |
| **Platform fee** | InfluTo's 10% of the same price. You pay commission + fee; nothing per month. |
| **Wallet** | Your prepaid balance. Each conversion reserves its commission and fee from it. |
| **Payout** | The monthly Stripe transfer to a creator, on the 1st, once they have $20 or more. |

## One referral, start to finish

<!-- steps -->

### A creator shares their link or code

They post `https://influ.to/fitnow/MAYA` in a bio or a video description, or say "use code MAYA" in a podcast. Clicks on the link are counted after removing repeats and bot traffic.

### Someone installs your app

The SDK in your app calls `checkAttribution` at launch. InfluTo connects the install to Maya in one of three ways:

- **Exact:** the person types `MAYA` into your code field, or a link carries the code into the app (web and Capacitor apps), or your app already knows the code and sets it for RevenueCat.
- **Fallback:** link-click matching connects the install to a recent tap on Maya's link, within 72 hours.
- **No match:** the install counts as organic. Nobody is charged for it.

Details: [Attribution](https://docs.influ.to/advanced/attribution.md).

### They buy

The purchase goes through the App Store or Google Play as usual. InfluTo hears about it from RevenueCat's webhook, or from the SDK on store-direct apps, and verifies it with the store before anything else happens. Free trials earn nothing until they convert to paid.

### The commission is reserved

For a $9.99 monthly subscription with a 30% commission, Maya earns $3.00 and InfluTo's fee is $1.00, so $4.00 is reserved from your wallet. Every renewal repeats this for as long as the person stays subscribed — the first creator to bring a user keeps them. Refunds reverse the commission.

### Maya gets paid

On the 1st of each month InfluTo pays out the previous month's earnings through Stripe Connect, to creators in 33 countries, once their balance is at least $20. Smaller balances roll over to the next month.

<!-- /steps -->

## Who does what

| Part | Runs where | Job |
|---|---|---|
| InfluTo SDK | In your app | Records the install and the referral, lets users type codes, reports store purchases on store-direct apps |
| RevenueCat (if you use it) | RevenueCat's servers | Sends purchase events to InfluTo's webhook, carrying the referral code as a subscriber attribute |
| App Store / Google Play | Apple, Google | The source of truth: InfluTo checks every purchase, renewal and refund with them |
| InfluTo | influ.to | Matches purchases to creators, reserves commission from your wallet, pays creators, shows you the numbers |

## Sandbox and production

One API key covers both. InfluTo tells sandbox and TestFlight purchases apart from real ones: they show up in **Real-Time Events** so you can test, but they never move money, change your stats or count towards payouts.

## Where to go next

<!-- cards -->
- [Quick start](https://docs.influ.to/quick-start.md) — Do the whole setup once, end to end.
- [Choose an SDK](https://docs.influ.to/sdk.md) — Install for your stack.
- [Commissions and fees](https://docs.influ.to/platform/commissions.md) — The exact rules for what creators earn and what you pay.
- [Wallet and payouts](https://docs.influ.to/platform/wallet.md) — Deposits, reservations, low balance and the monthly payout run.
<!-- /cards -->

---

<!-- https://docs.influ.to/sdk -->
# Choose an SDK

> Which InfluTo SDK fits your app — React Native and Expo, native iOS, native Android, Flutter, or web and Capacitor — and what each one needs for RevenueCat or store-direct.

Install exactly one InfluTo SDK per app: the one for the language your app is written in. All five follow the same wire contract, have the same methods, and support both purchase-validation paths, so everything else in these docs applies whichever you pick.

## Pick by stack

| Your app is built with | Use | Guide |
|---|---|---|
| React Native, Expo | `@influto/react-native-sdk` | [React Native & Expo](https://docs.influ.to/sdk/react-native.md) |
| Swift — SwiftUI or UIKit | `influto-ios` (Swift Package Manager) | [iOS](https://docs.influ.to/sdk/ios.md) |
| Kotlin or Java | `to.influ:android-sdk` | [Android](https://docs.influ.to/sdk/android.md) |
| Flutter (Dart) | `influto` | [Flutter](https://docs.influ.to/sdk/flutter.md) |
| Capacitor, Ionic, Cordova, a PWA or a website wrapped as an app | `@influto/web` | [Web & Capacitor](https://docs.influ.to/sdk/web.md) |
| Anything else (Unity, Kotlin Multiplatform, a backend) | The HTTP API | [HTTP API](https://docs.influ.to/reference/http-api.md) |

A React Native app with native iOS and Android modules still uses the React Native SDK — one SDK per app, not per platform.

## Packages

| Your app | Package | Registry | Latest | Source |
|---|---|---|---|---|
| React Native / Expo | `@influto/react-native-sdk` | [npm](https://www.npmjs.com/package/@influto/react-native-sdk) | 1.7.0 | [influto/influto-react-native](https://github.com/influto/influto-react-native) |
| iOS (Swift) | `github.com/influto/influto-ios` | [Swift Package Manager](https://swiftpackageindex.com/influto/influto-ios) | 1.1.1 | [influto/influto-ios](https://github.com/influto/influto-ios) |
| Android (Kotlin) | `to.influ:android-sdk` | [Maven Central](https://central.sonatype.com/artifact/to.influ/android-sdk) | 1.1.1 | [influto/influto-android](https://github.com/influto/influto-android) |
| Flutter (Dart) | `influto` | [pub.dev](https://pub.dev/packages/influto) | 1.1.1 | [influto/influto-flutter](https://github.com/influto/influto-flutter) |
| Web / Capacitor / PWA | `@influto/web` | [npm](https://www.npmjs.com/package/@influto/web) | 1.0.1 | [npm package](https://www.npmjs.com/package/@influto/web) |

## What every SDK does

- `initialize` once at startup with the app's API key — throws on failure.
- `checkAttribution` at launch to find out whether the install was referred — never throws.
- `identifyUser` when you know who the user is, so purchases can be matched to the referral.
- `validateCode` / `applyCode` and a ready-made code field for codes people type in.
- `checkAccess` for free-access codes, `reportPurchase` for store-direct apps, `trackEvent` for funnel events.

Every method, with signatures for each platform: [SDK reference](https://docs.influ.to/reference/sdk.md).

## Purchases: what each SDK needs

Choose RevenueCat or store-direct per app ([how to choose](https://docs.influ.to/integrations.md)). What you add depends on the SDK:

| SDK | RevenueCat: tagging the subscriber | Store-direct: automatic purchase capture |
|---|---|---|
| React Native | Automatic when `react-native-purchases` is installed | Needs `expo-iap` or `react-native-iap` installed |
| iOS | Pass a `revenueCatAttributeSetter` in the config | Built in (StoreKit 2) |
| Android | Automatic, or pass a `revenueCatAttributeSetter` | Add `to.influ:android-sdk-billing` |
| Flutter | Pass a `revenueCatHook` in the config | Add `influto_iap` and enable its observer |
| Web | Pass a `revenueCat` binding | Pass a `purchaseSource` (Capacitor, Cordova or Play Digital Goods) |

Automatic capture only runs on apps set to store-direct, so it can never double-report a RevenueCat app. Each SDK guide shows the exact code.

## Requirements

| SDK | Minimum |
|---|---|
| React Native | React Native 0.60+, `@react-native-async-storage/async-storage` |
| iOS | iOS 16, Swift 5.9 (also macOS 13, tvOS 16, watchOS 9) |
| Android | minSdk 24, Java 17 toolchain |
| Flutter | Flutter 3.22, Dart 3.4 |
| Web | Any ES2019 browser or WebView; Capacitor plugins optional |

None of the SDKs use advertising identifiers or ask for App Tracking Transparency. What they send, and what to declare in the stores: [Privacy & App Store review](https://docs.influ.to/advanced/privacy.md).

---

<!-- https://docs.influ.to/sdk/react-native -->
# Add InfluTo to a React Native or Expo app

> Install the InfluTo SDK in a React Native or Expo app, detect referred installs, accept typed codes, and send purchases through RevenueCat or the stores.

`@influto/react-native-sdk` adds creator attribution to a React Native or Expo app. It tells you whether an install came from a creator's link or code, lets people type a creator's code, and gets each purchase to InfluTo through RevenueCat or straight from the App Store and Google Play. Plan for an afternoon; most of it goes into the purchase side.

| | |
|---|---|
| Package | `@influto/react-native-sdk` (UI components: `@influto/react-native-sdk/ui`) |
| Latest version | 1.7.0 |
| Registry | [npm](https://www.npmjs.com/package/@influto/react-native-sdk) |
| Requires | React Native 0.60+ and React 16.8+, `@react-native-async-storage/async-storage` 2.x |
| Works with | Expo (managed and bare) and bare React Native, iOS and Android |
| Source | [github.com/influto/influto-react-native](https://github.com/influto/influto-react-native) (MIT) |

## Install

```bash
npm install @influto/react-native-sdk
# AsyncStorage is a native module — install it in the app too
npm install @react-native-async-storage/async-storage
```

AsyncStorage holds the SDK's local state. Install it in your app as well, so autolinking picks up its native module. In a bare React Native project, run `pod install` in `ios/` afterwards.

On Expo there is no config plugin to add: the SDK is plain JavaScript on top of AsyncStorage, so it runs in Expo Go, development builds and production builds alike.

The SDK also uses these packages when your app already has them. You don't import anything for this:

| Package | What the SDK does with it |
|---|---|
| `react-native-purchases` | Sets the RevenueCat attributes `influto_code` and `influto_referral` when a referral is found or a code is applied |
| `expo-iap` or `react-native-iap` | Captures store purchases on store-direct apps (`expo-iap` is used if both are installed) |
| `react-native-device-info` | Adds the device brand and model to install tracking |

Store libraries contain native code, so test purchases in a development build rather than Expo Go.

## Initialize

```tsx
import InfluTo from '@influto/react-native-sdk';

// Call once at startup (e.g. in App.tsx)
await InfluTo.initialize({
  apiKey: 'YOUR_API_KEY',
  debug: __DEV__,
});
// RevenueCat apps: nothing else to wire — if react-native-purchases is
// installed, the SDK sets the influto_code subscriber attribute itself.
```

Call `initialize` once, as early as possible, and wait for it before calling anything else. If it hasn't succeeded, `checkAttribution` and `reportPurchase` throw "not initialized" and the other methods return empty results.

`initialize` throws when it fails — a wrong key, no network. Catch it, log it, and carry on: the next launch tries again. A typical startup, in order:

```tsx file="App.tsx"
import { useEffect } from 'react';
import Purchases from 'react-native-purchases';
import InfluTo from '@influto/react-native-sdk';

export default function App() {
  useEffect(() => {
    (async () => {
      Purchases.configure({ apiKey: REVENUECAT_API_KEY }); // RevenueCat apps: configure it first
      try {
        await InfluTo.initialize({
          apiKey: process.env.EXPO_PUBLIC_INFLUTO_API_KEY!,
          appVersion: '1.4.0',
          debug: __DEV__,
        });
      } catch (error) {
        console.warn('InfluTo initialize failed', error); // retried on the next launch
        return;
      }
      const attribution = await InfluTo.checkAttribution();
      await InfluTo.identifyUser(await Purchases.getAppUserID());
    })();
  }, []);
  // …
}
```

The API key starts with `it_` and is on **Setup & SDK**; one key works for development and production. Keep it out of committed source — for example in a gitignored `.env` read through Expo's `EXPO_PUBLIC_` variables.

| Option | Type | Default | What it does |
|---|---|---|---|
| `apiKey` | `string` | required | The app's SDK key (`it_…`) |
| `debug` | `boolean` | `false` | Logs `[InfluTo]` lines to the console |
| `appVersion` | `string` | `"unknown"` | Your app version, sent with the startup call |
| `autoCapture` | `boolean` | `true` | Store-direct apps: report purchases from `expo-iap` / `react-native-iap` automatically. Set `false` if you call `reportPurchase` yourself |
| `oneTimeProductIds` | `string[]` | none | Your Android one-time and consumable product IDs, so captured purchases are validated as one-time purchases |

## Detect referred users

```tsx
const attribution = await InfluTo.checkAttribution();
if (attribution.attributed) {
  // User came from a referral — show a special offer / extended trial.
  // The SDK also sets the RevenueCat attributes influto_code + influto_referral.
  console.log('Referred by', attribution.referralCode);
}
```

| Field | Meaning |
|---|---|
| `attributed` | `true` when the install came from a creator's link or code |
| `referralCode` | The creator's code, uppercase |
| `attributionMethod` | `ip_device_match` (link-click matching) or `manual_entry` (a code the user applied) |
| `clickedAt` | When the link was clicked, or the code applied |
| `message` | A short explanation, for logs |

Attribution is decided once per install and stored on the device; later calls return the stored answer without a request. Only a failed request is retried, on the next call. A reinstall starts over.

`checkAttribution` is fail-soft: on a network or server error it returns `attributed: false` and stores nothing. Link-click matching only counts taps from the last 72 hours — see [attribution](https://docs.influ.to/advanced/attribution.md). To show referred users a better offer, see [Reward referred users](https://docs.influ.to/guides/referral-offers.md).

## Identify the user

Call `identifyUser` as soon as you know who the user is, with the same ID your purchases are keyed on — for RevenueCat, the app user ID:

```tsx
await InfluTo.identifyUser(await Purchases.getAppUserID());
```

It matters for three things: InfluTo uses it to credit a RevenueCat purchase when the `influto_code` attribute didn't make it, `checkAccess` uses it for free-access codes, and `reportPurchase` sends it by default. Call it once per sign-in, ideally in the user's first session — not on every render.

## Track events

```tsx
await InfluTo.trackEvent({
  eventType: 'paywall_viewed',
  appUserId: userId,
  properties: { placement: 'onboarding' },
});
```

Events show on **Real-Time Events** and help you read the funnel. They never create conversions or commission — only validated purchases do. Every call gets an event ID, so an accidental double call counts once. For `trial_started`, `subscription_purchased` and `subscription_renewed` the ID is derived from the event, user and properties, so the same event counts once even across launches; include something that changes per occurrence (a transaction ID, say) in `properties` when the event can repeat. For your own once-only events, pass `eventId` yourself.

## Let users type a code

```tsx
// Validate, then apply a code the user typed
const result = await InfluTo.applyCode('FITGURU30');
if (result.valid && result.applied) {
  // Unlock the offer
}

// Or drop in the ready-made UI:
import { ReferralCodeInput } from '@influto/react-native-sdk/ui';
<ReferralCodeInput onApplied={(result) => {/* ... */}} />

// Free-access codes (INFLU-… or your comp codes): redeem with
// setReferralCode(code) after identifyUser (or pass appUserId) — grantsAccess
// === true means unlock premium now — and gate premium on (await InfluTo.checkAccess()).hasAccess.
```

`applyCode(code, appUserId?)` validates the code and applies it if it's valid. Codes are trimmed and uppercased for you. An invalid code comes back with `valid: false` and an `error_code`: `INVALID_FORMAT`, `CODE_NOT_FOUND`, `CODE_EXPIRED` or `NETWORK_ERROR`. If you build your own field, write your own copy: `message` and `influencer` can contain the creator's personal name.

The ready-made field is `ReferralCodeInput` from `@influto/react-native-sdk/ui`:

| Prop | Default | Notes |
|---|---|---|
| `onApplied(result)` | — | The code was valid and applied |
| `onValidated(result)` | — | After every validation, valid or not |
| `onSkip()` | — | The skip button was pressed |
| `appUserId` | identified user | The user to bind the code to; free-access codes need one |
| `autoPrefill` / `autoValidate` | `true` / `false` | Pre-fill the code from a link-attributed install, and validate it on mount |
| `validateOnBlur` / `showSkipButton` | `true` / `true` | |
| `showCampaignName` / `showReferrerName` | `false` / `false` | Show a creator's name only with their consent |
| `colors`, `fonts`, `labels`, `style` | — | Theming and translated labels |

More on the UX: [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md). All props: [UI components](https://docs.influ.to/reference/ui.md).

## Purchases

InfluTo only pays commission on purchases it has verified with the store. Choose exactly one path per platform — see [Choose a validation path](https://docs.influ.to/integrations.md).

### RevenueCat

With `react-native-purchases` installed, there's nothing to wire in code: when `checkAttribution` finds a referral, or a code is applied, the SDK sets `influto_code` (the code) and `influto_referral` (the string `"true"`) on the RevenueCat subscriber. Then connect the webhook — see [RevenueCat](https://docs.influ.to/integrations/revenuecat.md).

> [!IMPORTANT]
> The SDK writes the attribute once, when the referral is found. If RevenueCat isn't configured at that moment, the write is skipped and not retried. Call `Purchases.configure` before `checkAttribution`, and call `identifyUser` with the RevenueCat app user ID as the fallback.

### Store-direct

Install `expo-iap` or `react-native-iap`. When the app is set to store-direct in **Settings → Validation** and `autoCapture` isn't `false`, `initialize` starts listening for new purchases and back-fills existing ones. Each purchase is reported once; without an IAP library, capture quietly does nothing. You can also drive it yourself with `enableAutoPurchaseCapture({ backSync, oneTimeProductIds })`, `disableAutoPurchaseCapture()` and `syncExistingPurchases()`.

To report purchases yourself instead, set `autoCapture: false` and call `reportPurchase` after each successful purchase:

```tsx
// Store-direct only (no RevenueCat). With expo-iap or react-native-iap installed,
// purchases are captured automatically on store-direct apps. To report
// manually instead, pass the store-signed proof:
await InfluTo.reportPurchase({
  platform: 'ios',                 // or 'android'
  signedTransaction: jwsString,    // iOS: StoreKit 2 JWS
  // purchaseToken: token,         // Android: Play Billing purchaseToken
});
```

- `reportPurchase` throws on failure. The error message includes the HTTP status, for example `API request failed: 503 - …`.
- `503`: the exchange rate was briefly unavailable — retry later. Reports are idempotent.
- `400`: the platform isn't set to store-direct yet. `409` (Android one-time products): the purchase isn't in the PURCHASED state yet.
- Android one-time and consumable products need `productId`, plus `price` and `currency` from the product details. Captured purchases only carry a price when the IAP library puts one on the purchase, and a one-time purchase without a price is recorded at $0 — report those yourself.

Set-up, credentials and testing: [Store-direct](https://docs.influ.to/integrations/store-direct.md).

## Free-access codes

Free-access codes give a user premium without a purchase. Redeem one with `setReferralCode(code, appUserId)` after `identifyUser`, or pass the user ID — a code with no user is refused. The result tells you what happened: `grantsAccess`, `freeAccess`, `entitlement` and `expiresAt`. `applyCode` doesn't return these flags; after it, `result.campaign?.campaign_type === 'FREE_ACCESS'` tells you the code was a free-access code.

Gate premium on your store entitlement or InfluTo's answer:

```tsx
const premium = entitlementActive || (await InfluTo.checkAccess()).hasAccess;
```

`checkAccess(appUserId?)` uses the identified user when you don't pass one, caches a positive answer for 5 minutes, never caches a negative one, and returns `hasAccess: false` on errors. See [Free access codes](https://docs.influ.to/platform/creator-access-codes.md).

## Verify

After the first successful `initialize`, **Setup & SDK** shows "Integrated — SDK connected" with the platform and SDK version it last saw. With `debug: true` the SDK logs each step, and **Real-Time Events** lists your events and purchases. For the full end-to-end test and the integration status checklist, see [Verify the integration](https://docs.influ.to/integrations/testing.md).

To test attribution again on the same device, `clearAttribution()` forgets the stored attribution, code and user ID. It's for testing only — a reinstall gives a cleaner start.

## React Native notes

- **AsyncStorage** must be in your app's own dependencies, or its native module isn't linked.
- **Order matters for RevenueCat**: configure `react-native-purchases`, then `initialize`, then `checkAttribution`.
- **Initialize once.** Put it at the app root, not in a screen that mounts repeatedly, and don't call `identifyUser` from a render path.
- **Expo Go** runs the SDK, but not store libraries. Auto-capture does nothing there, which is safe.
- **Android one-time products**: list them in `oneTimeProductIds`, and report them yourself if your IAP library doesn't expose the price.

---

<!-- https://docs.influ.to/sdk/ios -->
# Add InfluTo to an iOS app

> Install the InfluTo Swift package, detect referred installs, accept typed codes, and report StoreKit 2 purchases or tag RevenueCat subscribers.

The InfluTo Swift package adds creator attribution to a native iOS app built with SwiftUI or UIKit. It tells you whether an install came from a creator's link or code, lets people type a creator's code, and gets each purchase to InfluTo — through RevenueCat, or straight from StoreKit 2. Plan for an afternoon; most of it goes into the purchase side.

| | |
|---|---|
| Package | Swift package `https://github.com/influto/influto-ios`, library and module `InfluTo` |
| Latest version | 1.1.1 |
| Registry | Swift Package Manager ([Swift Package Index](https://swiftpackageindex.com/influto/influto-ios)) |
| Requires | iOS 16+, Swift 5.9 (Xcode 15) or newer. Also builds for macOS 13, tvOS 16 and watchOS 9 |
| Dependencies | None — Foundation, StoreKit 2 and CryptoKit only |
| Source | [github.com/influto/influto-ios](https://github.com/influto/influto-ios) (MIT) |

## Install

```swift
// Xcode → File → Add Package Dependencies →
//   https://github.com/influto/influto-ios   (from 1.1.1)
// Or in Package.swift:
.package(url: "https://github.com/influto/influto-ios.git", from: "1.1.1")
```

Add the `InfluTo` library to your app target. The SDK ships through Swift Package Manager only; there is no CocoaPods pod.

## Initialize

```swift
import InfluTo

// Call once at launch
var config = InfluToConfig(apiKey: "YOUR_API_KEY", debug: true)
// RevenueCat apps: hand the SDK a setter so it can tag the subscriber
// config.revenueCatAttributeSetter = { attrs in Purchases.shared.attribution.setAttributes(attrs) }
try await InfluTo.initialize(config)
```

Every SDK method is `async`. Call `initialize` once at launch, from a `Task`, and wait for it before calling anything else. It throws when it fails — a wrong key, no network — so catch the error, log it, and carry on; the next launch tries again. A typical startup, in order:

```swift file="MyApp.swift"
import SwiftUI
import InfluTo
import RevenueCat // only if you use RevenueCat

@main
struct MyApp: App {
    init() {
        Purchases.configure(withAPIKey: "appl_…") // RevenueCat apps: configure it first
        Task { await startInfluTo() }
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

func startInfluTo() async {
    var config = InfluToConfig(
        apiKey: Bundle.main.object(forInfoDictionaryKey: "INFLUTO_API_KEY") as? String ?? "",
        appVersion: Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
    )
    config.revenueCatAttributeSetter = { attrs in
        Purchases.shared.attribution.setAttributes(attrs)
    }
    do {
        try await InfluTo.initialize(config)
    } catch {
        print("InfluTo initialize failed: \(error)") // retried on the next launch
        return
    }
    let attribution = await InfluTo.checkAttribution()
    await InfluTo.identifyUser(Purchases.shared.appUserID)
}
```

In UIKit, start the same `Task` from `application(_:didFinishLaunchingWithOptions:)`.

The API key starts with `it_` and is on **Setup & SDK**; one key works for development and production. Keep it out of committed source — for example in an `.xcconfig` file that isn't checked in, exposed to the app through `Info.plist` as above.

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `apiKey` | `String` | required | The app's SDK key (`it_…`) |
| `debug` | `Bool` | `false` | Prints `[InfluTo]` lines |
| `appVersion` | `String?` | `nil` (sent as `"unknown"`) | Your app version, sent with the startup call |
| `autoCapture` | `Bool` | `true` | Store-direct apps: observe StoreKit 2 transactions and report them |
| `revenueCatAttributeSetter` | `(@Sendable ([String: String]) -> Void)?` | `nil` | RevenueCat apps: how the SDK sets the subscriber attributes |

## Detect referred users

```swift
let attribution = await InfluTo.checkAttribution()
if attribution.attributed {
  // User came from a referral — show a special offer.
  print("Referred by \(attribution.referralCode ?? "")")
}
```

`AttributionResult` has these properties:

| Property | Meaning |
|---|---|
| `attributed` | `true` when the install came from a creator's link or code |
| `referralCode` | The creator's code, uppercase |
| `attributionMethod` | `"ip_device_match"` (link-click matching) or `"manual_entry"` (a code the user applied) |
| `clickedAt` | When the link was clicked, or the code applied |
| `message` | A short explanation, for logs |

Attribution is decided once per install and stored on the device; later calls return the stored answer without a request. Only a failed request is retried, on the next call. A reinstall starts over.

`checkAttribution` never throws. On a network or server error — or if `initialize` hasn't succeeded — it returns `attributed == false` and stores nothing. Link-click matching only counts taps from the last 72 hours — see [attribution](https://docs.influ.to/advanced/attribution.md). To show referred users a better offer, see [Reward referred users](https://docs.influ.to/guides/referral-offers.md).

## Identify the user

Call `identifyUser` as soon as you know who the user is, with the same ID your purchases are keyed on — for RevenueCat, the app user ID:

```swift
await InfluTo.identifyUser(Purchases.shared.appUserID)
```

It matters for three things: InfluTo uses it to credit a RevenueCat purchase when the `influto_code` attribute didn't make it, `checkAccess` uses it for free-access codes, and `reportPurchase` sends it by default. Call it once per sign-in, ideally in the user's first session.

## Track events

```swift
await InfluTo.trackEvent(TrackEventOptions(
    eventType: "paywall_viewed",
    appUserId: userID,
    properties: ["placement": AnyCodable("onboarding")]
))
```

Events show on **Real-Time Events** and help you read the funnel. They never create conversions or commission — only validated purchases do. Every call gets an event ID, so an accidental double call counts once. For `trial_started`, `subscription_purchased` and `subscription_renewed` the ID is derived from the event, user and properties, so the same event counts once even across launches; include something that changes per occurrence (a transaction ID, say) in `properties` when the event can repeat. For your own once-only events, pass `eventId`.

## Let users type a code

```swift
// Validate + apply a code the user typed
let result = await InfluTo.applyCode("FITGURU30")
if result.valid && result.applied == true {
  // Unlock the offer
}

// Or drop in the SwiftUI field: InfluToReferralCodeInput(onApplied: { result in … })
// Free-access codes (after identifyUser): setReferralCode(code).grantsAccess == true
// → unlock premium, and gate premium on (await InfluTo.checkAccess()).hasAccess.
```

`applyCode(_:appUserId:)` validates the code and applies it if it's valid; the result's `applied` tells you whether it was applied. Codes are trimmed and uppercased for you. An invalid code comes back with `valid == false` and an `errorCode`: `INVALID_FORMAT`, `CODE_NOT_FOUND`, `CODE_EXPIRED` or `NETWORK_ERROR`. If you build your own field, write your own copy: `message` and `influencer` can contain the creator's personal name.

The ready-made field is the SwiftUI view `InfluToReferralCodeInput`. It validates as the user types and applies the code when they tap the button:

```swift
InfluToReferralCodeInput(appUserId: userID, onApplied: { result in
    // the code is applied — unlock the offer
})
```

| Parameter | Default | Notes |
|---|---|---|
| `appUserId` | identified user | The user to bind the code to; free-access codes need one |
| `autoPrefill` / `autoValidate` | `true` / `false` | Pre-fill the code from a link-attributed install, and validate it right away |
| `showCampaignName` / `showReferrerName` | `false` / `false` | Show a creator's name only with their consent |
| `title`, `labels` | — | Heading and translated texts (`placeholder`, `apply`, `valid`, `invalid`) |
| `onValidated`, `onApplied` | — | Called after each validation, and after the code is applied |

In UIKit, host it in a `UIHostingController`. More on the UX: [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md). All parameters: [UI components](https://docs.influ.to/reference/ui.md).

## Purchases

InfluTo only pays commission on purchases it has verified with the store. Choose exactly one path per platform — see [Choose a validation path](https://docs.influ.to/integrations.md).

### RevenueCat

Pass a `revenueCatAttributeSetter`, as in the startup example above. When `checkAttribution` finds a referral, or a code is applied, the SDK calls it with `influto_code` (the code) and `influto_referral` (the string `"true"`). Then connect the webhook — see [RevenueCat](https://docs.influ.to/integrations/revenuecat.md).

> [!IMPORTANT]
> Without the setter, nothing sets the attribute on iOS. The SDK calls it once, when the referral is found, so configure RevenueCat before `checkAttribution`, and call `identifyUser` with the RevenueCat app user ID as the fallback.

### Store-direct

StoreKit 2 capture is built in. When the app is set to store-direct in **Settings → Validation** and `autoCapture` is `true`, `initialize` starts observing `Transaction.updates` and back-fills your current entitlements and unfinished transactions. Each transaction is reported once, keyed on its original transaction ID. The SDK never calls `finish()` — your app still finishes its transactions. You can also drive it yourself with `startPurchaseObservation()`, `stopPurchaseObservation()` and `syncExistingPurchases()`.

To report a purchase as soon as it happens, pass the verification result from `product.purchase()`:

```swift
// Store-direct only (no RevenueCat). Report right after a purchase — StoreKit
// doesn't send purchases made in your app to the background listener, and
// reports are de-duplicated, so this is safe alongside auto-capture:
if case .success(let verification) = try await product.purchase() {
  let r = try await InfluTo.reportPurchase(verification: verification)
}
```

InfluTo de-duplicates repeated reports of the same transaction, so a purchase reported both here and by auto-capture still counts once. `reportPurchase(jws:)` takes a raw StoreKit 2 signed transaction instead. Both throw:

```swift
do {
    _ = try await InfluTo.reportPurchase(verification: verification)
} catch InfluToError.retryable(_) {
    // 503: the exchange rate was briefly unavailable — try again later
} catch InfluToError.notConfigured(_) {
    // 400: iOS isn't set to store-direct yet
} catch {
    print("InfluTo reportPurchase failed: \(error)")
}
```

Optionally, tie the transaction to your user ID with StoreKit's account token: `product.purchase(options: [.appAccountToken(InfluTo.appAccountToken(forUserID: userID))])`. It's the same UUID every time for a given user ID.

Set-up, credentials, the Sandbox/Production environment setting and testing: [Store-direct](https://docs.influ.to/integrations/store-direct.md).

## Free-access codes

Free-access codes give a user premium without a purchase. Redeem one with `setReferralCode(_:appUserId:)` after `identifyUser`, or pass the user ID — a code with no user is refused. The result tells you what happened: `grantsAccess`, `freeAccess`, `entitlement` and `expiresAt`. `applyCode` doesn't return these flags; after it, `result.campaign?.campaignType == "FREE_ACCESS"` tells you the code was a free-access code.

Gate premium on your store entitlement or InfluTo's answer:

```swift
let access = await InfluTo.checkAccess()
let premium = entitlementActive || access.hasAccess
```

`checkAccess(appUserId:)` uses the identified user when you don't pass one, caches a positive answer for 5 minutes (across launches too), never caches a negative one, and returns `hasAccess == false` on errors. See [Free access codes](https://docs.influ.to/platform/creator-access-codes.md).

## Verify

After the first successful `initialize`, **Setup & SDK** shows "Integrated — SDK connected" with the platform and SDK version it last saw. With `debug: true` the SDK prints each step, and **Real-Time Events** lists your events and purchases. For the full end-to-end test and the integration status checklist, see [Verify the integration](https://docs.influ.to/integrations/testing.md).

To test attribution again on the same device, `clearAttribution()` forgets the stored attribution, code and user ID. It's for testing only — deleting and reinstalling the app gives a cleaner start.

## iOS notes

- **Privacy manifest included.** The package ships `PrivacyInfo.xcprivacy`: no tracking, no tracking domains, and the data types it collects (not linked to identity). It doesn't use the advertising identifier, so no App Tracking Transparency prompt is needed. Details for your App Privacy label: [Privacy & App Store](https://docs.influ.to/advanced/privacy.md).
- **StoreKit 2 only.** Store-direct reporting needs the signed transaction (JWS); never send the unsigned JSON representation. The SDK sends the JWS even when on-device verification fails, and InfluTo verifies it on the server.
- **Sandbox vs Production.** TestFlight and sandbox purchases only verify when the app's Apple environment is set to Sandbox in **Settings → Validation**.
- **RevenueCat order**: configure RevenueCat, then `initialize`, then `checkAttribution`.
- **Local state** lives in the `com.influto.sdk` `UserDefaults` suite and survives app updates; deleting the app removes it.

---

<!-- https://docs.influ.to/sdk/android -->
# Add InfluTo to an Android app

> Add the InfluTo Android SDK from Maven Central, detect referred installs, accept typed codes, and connect RevenueCat or Google Play purchases.

The InfluTo Android SDK adds creator attribution to a native Android app written in Kotlin. It tells you whether an install came from a creator's link or code, lets people type a creator's code, and gets each purchase to InfluTo — through RevenueCat, or straight from Google Play Billing. Plan for an afternoon; most of it goes into the purchase side.

| | |
|---|---|
| Package | `to.influ:android-sdk`, plus optional `to.influ:android-sdk-ui` (Compose) and `to.influ:android-sdk-billing` (Play Billing capture) |
| Latest version | 1.1.1 (all three artifacts) |
| Registry | [Maven Central](https://central.sonatype.com/artifact/to.influ/android-sdk) |
| Requires | minSdk 24, Java 17. Built with Kotlin 2.2, compileSdk 35 |
| Dependencies | Core: kotlinx-coroutines only |
| Source | [github.com/influto/influto-android](https://github.com/influto/influto-android) (MIT) |

## Install

```kotlin
// build.gradle.kts
dependencies {
    implementation("to.influ:android-sdk:1.1.1")
    // optional: Compose code field (InfluToReferralCodeInput)
    implementation("to.influ:android-sdk-ui:1.1.1")
    // optional: store-direct purchase auto-capture
    implementation("to.influ:android-sdk-billing:1.1.1")
}
```

The artifacts are on Maven Central, so `mavenCentral()` must be in your repositories. Add only what you need — each add-on brings the core SDK with it:

| Artifact | Add it when | What it brings |
|---|---|---|
| `android-sdk` | Always | The SDK; adds the `INTERNET` permission |
| `android-sdk-ui` | You want the ready-made Compose code field | `InfluToReferralCodeInput` (Material 3) |
| `android-sdk-billing` | Your app is store-direct (no RevenueCat) | Automatic purchase capture. Adds Google Play Billing Library 9.0.0 (`billing-ktx`) to your build and the `com.android.vending.BILLING` permission |

The core and billing artifacts ship their own R8/ProGuard rules; there is nothing to add.

## Initialize

```kotlin
import to.influ.sdk.InfluTo
import to.influ.sdk.InfluToConfig

// Call once at startup. initialize() is a suspend function — launch it from a
// coroutine, or use the callback overload: InfluTo.initialize(context, config) { result -> }
lifecycleScope.launch {
  InfluTo.initialize(applicationContext, InfluToConfig(
    apiKey = "YOUR_API_KEY",
    // RevenueCat apps: optional explicit setter (otherwise found by reflection)
    // revenueCatAttributeSetter = { attrs -> Purchases.sharedInstance.setAttributes(attrs) },
  ))
}
```

`initialize` is a `suspend` function. Call it once at startup and wait for it before calling anything else — if it hasn't succeeded, `checkAttribution` and `reportPurchase` throw `InfluToError.NotInitialized`. It throws when it fails (a wrong key, no network), so catch the error, log it, and carry on; the next launch tries again. A typical startup, in order:

```kotlin file="MyApp.kt"
class MyApp : Application() {
    private val appScope = MainScope()

    override fun onCreate() {
        super.onCreate()
        // RevenueCat apps: configure it first
        Purchases.configure(PurchasesConfiguration.Builder(this, "goog_…").build())

        appScope.launch {
            try {
                InfluTo.initialize(this@MyApp, InfluToConfig(
                    apiKey = BuildConfig.INFLUTO_API_KEY,
                    appVersion = BuildConfig.VERSION_NAME,
                ))
            } catch (e: Exception) {
                Log.w("InfluTo", "initialize failed", e) // retried on the next launch
                return@launch
            }
            val attribution = InfluTo.checkAttribution()
            InfluTo.identifyUser(Purchases.sharedInstance.appUserID)
        }
    }
}
```

The API key starts with `it_` and is on **Setup & SDK**; one key works for development and production. Keep it out of committed source — for example in a `BuildConfig` field filled from a Gradle property kept in `local.properties` or your CI secrets.

Not in a coroutine? Every network method also has a callback overload that takes `(Result<T>) -> Unit`, for example `InfluTo.initialize(context, config) { result -> … }`. Callbacks run on a background thread, so switch to the main thread before touching UI.

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `apiKey` | `String` | required | The app's SDK key (`it_…`) |
| `debug` | `Boolean` | `false` | Logs to Logcat under the `InfluTo` tag |
| `appVersion` | `String?` | `null` (sent as `"unknown"`) | Your app version, sent with the startup call |
| `autoCapture` | `Boolean` | `true` | Store-direct apps: start Play Billing capture when `android-sdk-billing` is on the classpath |
| `revenueCatAttributeSetter` | `((Map<String, String>) -> Unit)?` | `null` | RevenueCat apps: how the SDK sets subscriber attributes. If `null`, the SDK finds RevenueCat on its own |
| `oneTimeProductIds` | `Set<String>` | empty | Your one-time and consumable product IDs, so captured purchases are validated as one-time purchases |

## Detect referred users

```kotlin
val attribution = InfluTo.checkAttribution()   // suspend
if (attribution.attributed) {
  // User came from a referral — show a special offer.
  Log.d("App", "Referred by ${attribution.referralCode}")
}
```

`AttributionResult` has these properties:

| Property | Meaning |
|---|---|
| `attributed` | `true` when the install came from a creator's link or code |
| `referralCode` | The creator's code, uppercase |
| `attributionMethod` | `"ip_device_match"` (link-click matching) or `"manual_entry"` (a code the user applied) |
| `clickedAt` | When the link was clicked, or the code applied |
| `message` | A short explanation, for logs |

Attribution is decided once per install and stored on the device; later calls return the stored answer without a request. Only a failed request is retried, on the next call. A reinstall starts over.

`checkAttribution` is fail-soft: on a network or server error it returns `attributed = false` and stores nothing. Link-click matching only counts taps from the last 72 hours — see [attribution](https://docs.influ.to/advanced/attribution.md). To show referred users a better offer, see [Reward referred users](https://docs.influ.to/guides/referral-offers.md).

## Identify the user

Call `identifyUser` as soon as you know who the user is, with the same ID your purchases are keyed on — for RevenueCat, the app user ID:

```kotlin
InfluTo.identifyUser(Purchases.sharedInstance.appUserID)
```

It matters for three things: InfluTo uses it to credit a RevenueCat purchase when the `influto_code` attribute didn't make it, `checkAccess` uses it for free-access codes, and `reportPurchase` sends it by default. Call it once per sign-in, ideally in the user's first session.

## Track events

```kotlin
InfluTo.trackEvent(
    eventType = "paywall_viewed",
    appUserId = userId,
    properties = mapOf("placement" to "onboarding"),
)
```

Events show on **Real-Time Events** and help you read the funnel. They never create conversions or commission — only validated purchases do. Every call gets an event ID, so an accidental double call counts once. For `trial_started`, `subscription_purchased` and `subscription_renewed` the ID is derived from the event, user and properties, so the same event counts once even across launches; include something that changes per occurrence (an order ID, say) in `properties` when the event can repeat. For your own once-only events, pass `eventId`.

## Let users type a code

```kotlin
// Validate + apply a code the user typed
val result = InfluTo.applyCode("FITGURU30")   // suspend
if (result.valid && result.applied == true) {
  // Unlock the offer
}

// Or the Compose field (android-sdk-ui): InfluToReferralCodeInput(onApplied = { result -> … })
// Free-access codes (after identifyUser): setReferralCode(code).grantsAccess == true
// → unlock premium, and gate premium on InfluTo.checkAccess().hasAccess.
```

`applyCode(code, appUserId)` validates the code and applies it if it's valid; the result's `applied` tells you whether it was applied. Codes are trimmed and uppercased for you. An invalid code comes back with `valid = false` and an `errorCode`: `INVALID_FORMAT`, `CODE_NOT_FOUND`, `CODE_EXPIRED`, `NETWORK_ERROR` or `UNKNOWN`. If you build your own field, write your own copy: `message` and `influencer` can contain the creator's personal name.

The ready-made field is the composable `InfluToReferralCodeInput` from `android-sdk-ui`. It validates as the user types and applies the code when they tap the button:

```kotlin
InfluToReferralCodeInput(
    appUserId = userId,
    onApplied = { result -> /* the code is applied — unlock the offer */ },
)
```

| Parameter | Default | Notes |
|---|---|---|
| `appUserId` | identified user | The user to bind the code to; free-access codes need one |
| `autoPrefill` / `autoValidate` | `true` / `false` | Pre-fill the code from a link-attributed install, and validate it right away |
| `showCampaignName` / `showReferrerName` | `false` / `false` | Show a creator's name only with their consent |
| `title`, `placeholder`, `applyLabel`, `validMessage`, `invalidMessage` | — | Texts, for translation |
| `onValidated`, `onApplied`, `modifier` | — | Callbacks and layout |

More on the UX: [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md). All parameters: [UI components](https://docs.influ.to/reference/ui.md).

## Purchases

InfluTo only pays commission on purchases it has verified with the store. Choose exactly one path per platform — see [Choose a validation path](https://docs.influ.to/integrations.md).

### RevenueCat

There's nothing to wire in code: when `checkAttribution` finds a referral, or a code is applied, the SDK finds the RevenueCat SDK and sets `influto_code` (the code) and `influto_referral` (the string `"true"`) on the subscriber. To be explicit, pass the setter yourself:

```kotlin
revenueCatAttributeSetter = { attrs -> Purchases.sharedInstance.setAttributes(attrs) },
```

Then connect the webhook — see [RevenueCat](https://docs.influ.to/integrations/revenuecat.md). Don't add `android-sdk-billing` to a RevenueCat app; it isn't needed.

> [!IMPORTANT]
> The SDK writes the attribute once, when the referral is found. If RevenueCat isn't configured at that moment, the write is skipped and not retried. Configure RevenueCat before `checkAttribution`, and call `identifyUser` with the RevenueCat app user ID as the fallback.

### Store-direct

Add `android-sdk-billing`. When the app is set to store-direct in **Settings → Validation** and `autoCapture` is `true`, `initialize` starts an observer with its own Play Billing connection, which reports new purchases and sweeps existing ones each time the app starts. Each purchase is reported once, keyed on its purchase token; only purchases in the PURCHASED state are sent.

If your app has its own `BillingClient` (most do), also hand each purchase to the module from your `PurchasesUpdatedListener` so it's reported the moment it happens. It shares the same de-duplication, so nothing is reported twice:

```kotlin
override fun onPurchasesUpdated(result: BillingResult, purchases: MutableList<Purchase>?) {
    if (result.responseCode != BillingClient.BillingResponseCode.OK || purchases == null) return
    scope.launch {
        for (purchase in purchases) {
            InfluToBilling.report(context, purchase) // subscriptions
            // one-time products: InfluToBilling.report(context, purchase, oneTime = true, price = 4.99, currency = "EUR")
        }
    }
}
```

`InfluToBilling` also offers `startObservation(context, oneTimeProductIds)`, `stopObservation()` and `syncExistingPurchases(context)`.

To report purchases yourself with the core SDK instead, set `autoCapture = false` and call `reportPurchase`:

```kotlin
// Store-direct only (no RevenueCat). With the android-sdk-billing artifact on the
// classpath, purchases are captured AUTOMATICALLY. To report manually:
InfluTo.reportPurchase(
  purchaseToken = purchase.purchaseToken,
  // productId = "coins_100",  // one-time / consumable products only
)
```

```kotlin
try {
    InfluTo.reportPurchase(purchaseToken = purchase.purchaseToken)
} catch (e: InfluToError.Server) {
    if (e.retryable) { /* 503: exchange rate briefly unavailable — retry later */ }
    if (e.notConfigured) { /* 400: Android isn't set to store-direct yet */ }
}
```

- One-time and consumable products need `productId`, plus `price` and `currency` from the product details. Without `productId` the purchase is checked as a subscription and fails; without a price it's recorded at $0. Auto-capture adds both for products listed in `oneTimeProductIds`.
- `409` means a one-time purchase isn't in the PURCHASED state yet (for example, still pending).
- Other errors: `InfluToError.NotInitialized`, `Transport` (no connection) and `Decoding`.

Set-up, the Play service account and testing: [Store-direct](https://docs.influ.to/integrations/store-direct.md).

## Free-access codes

Free-access codes give a user premium without a purchase. Redeem one with `setReferralCode(code, appUserId = userId)` after `identifyUser`, or pass the user ID — a code with no user is refused. The `SetCodeResult` tells you what happened: `grantsAccess`, `freeAccess`, `entitlement` and `expiresAt`. `applyCode` doesn't return these flags; after it, `result.campaign?.campaignType == "FREE_ACCESS"` tells you the code was a free-access code.

Gate premium on your store entitlement or InfluTo's answer:

```kotlin
val premium = entitlementActive || InfluTo.checkAccess().hasAccess
```

`checkAccess(appUserId)` uses the identified user when you don't pass one, caches a positive answer for 5 minutes (across launches too), never caches a negative one, and returns `hasAccess = false` on errors. See [Free access codes](https://docs.influ.to/platform/creator-access-codes.md).

## Verify

After the first successful `initialize`, **Setup & SDK** shows "Integrated — SDK connected" with the platform and SDK version it last saw. With `debug = true` the SDK logs each step under the `InfluTo` tag, and **Real-Time Events** lists your events and purchases. For the full end-to-end test and the integration status checklist, see [Verify the integration](https://docs.influ.to/integrations/testing.md).

To test attribution again on the same device, `clearAttribution()` forgets the stored attribution, code and user ID. It's for testing only — clearing the app's storage or reinstalling gives a cleaner start.

## Android notes

- **Coroutines first.** Network methods are `suspend`; `getReferralCode()`, `getPrefilledCode()` and `clearAttribution()` are plain functions. Callback overloads deliver results on a background thread.
- **Initialize once,** in `Application.onCreate` or with an app-wide scope — an activity's `onCreate` runs again on every configuration change.
- **minSdk 24** and a Java 17 toolchain.
- **Permissions**: the core adds `INTERNET`; `android-sdk-billing` adds `com.android.vending.BILLING`. For the Play Data safety form, see [Privacy & App Store](https://docs.influ.to/advanced/privacy.md).
- **Play Billing version**: `android-sdk-billing` exposes Play Billing Library 9.0.0, which Gradle resolves together with your own Billing dependency.

---

<!-- https://docs.influ.to/sdk/flutter -->
# Add InfluTo to a Flutter app

> Add the influto package to a Flutter app, detect referred installs, accept typed codes, and connect RevenueCat or report store purchases with influto_iap.

The `influto` package adds creator attribution to a Flutter app on iOS and Android. It tells you whether an install came from a creator's link or code, lets people type a creator's code, and gets each purchase to InfluTo — through RevenueCat, or straight from the App Store and Google Play with the companion package `influto_iap`. Plan for an afternoon; most of it goes into the purchase side.

| | |
|---|---|
| Package | `influto`, plus the optional companion [`influto_iap`](https://pub.dev/packages/influto_iap) for automatic purchase capture |
| Latest version | 1.1.1 |
| Registry | [pub.dev](https://pub.dev/packages/influto) |
| Requires | Flutter 3.22+, Dart 3.4+ |
| Dependencies | `http` and `shared_preferences` (`influto_iap` adds `in_app_purchase`) |
| Source | [github.com/influto/influto-flutter](https://github.com/influto/influto-flutter) (MIT) |

## Install

```bash
flutter pub add influto
# optional: automatic store-direct purchase capture
flutter pub add influto_iap
```

Add `influto_iap` only if your app is store-direct (no RevenueCat) and sells through the `in_app_purchase` plugin. RevenueCat apps using `purchases_flutter` only need `influto`.

## Initialize

```dart
import 'package:influto/influto.dart';

// Call once at startup
await InfluTo.instance.initialize(
  InfluToConfig(
    apiKey: 'YOUR_API_KEY',
    // RevenueCat apps: let the SDK tag the subscriber
    // revenueCatHook: (attrs) => Purchases.setAttributes(attrs),
  ),
);
```

Call `initialize` once at startup and wait for it before calling anything else — if it hasn't succeeded, `checkAttribution` and `reportPurchase` throw an `InfluToException`. It throws when it fails (a wrong key, no network), so catch the error, log it, and carry on; the next launch tries again. Don't hold up your first frame for it. A typical startup, in order:

```dart file="main.dart"
import 'dart:async';
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:influto/influto.dart';
import 'package:purchases_flutter/purchases_flutter.dart'; // only if you use RevenueCat

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Purchases.configure(PurchasesConfiguration('appl_…')); // RevenueCat apps: configure it first
  runApp(const MyApp());
  unawaited(startInfluTo());
}

Future<void> startInfluTo() async {
  try {
    await InfluTo.instance.initialize(InfluToConfig(
      apiKey: const String.fromEnvironment('INFLUTO_API_KEY'),
      appVersion: '1.4.0',
      revenueCatHook: (attrs) => Purchases.setAttributes(attrs),
    ));
  } catch (e) {
    debugPrint('InfluTo initialize failed: $e'); // retried on the next launch
    return;
  }
  final attribution = await InfluTo.instance.checkAttribution();
  await InfluTo.instance.identifyUser(await Purchases.appUserID);
}
```

The API key starts with `it_` and is on **Setup & SDK**; one key works for development and production. Keep it out of committed source — for example pass it at build time with `--dart-define=INFLUTO_API_KEY=it_…` and read it with `String.fromEnvironment`.

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `apiKey` | `String` | required | The app's SDK key (`it_…`) |
| `debug` | `bool` | `false` | Prints `[InfluTo]` lines with `debugPrint` |
| `appVersion` | `String?` | `null` (sent as `'unknown'`) | Your app version, sent with the startup call |
| `autoCapture` | `bool` | `true` | Store-direct apps: lets the `influto_iap` observer report purchases. Set `false` if you call `reportPurchase` yourself |
| `revenueCatHook` | `Future<void> Function(Map<String, String>)?` | `null` | RevenueCat apps: how the SDK sets the subscriber attributes |
| `httpClient` | `http.Client?` | `null` | A custom HTTP client, for tests |

## Detect referred users

```dart
final attribution = await InfluTo.instance.checkAttribution();
if (attribution.attributed) {
  // User came from a referral — show a special offer.
  print('Referred by ${attribution.referralCode}');
}
```

`AttributionResult` has these fields:

| Field | Meaning |
|---|---|
| `attributed` | `true` when the install came from a creator's link or code |
| `referralCode` | The creator's code, uppercase |
| `attributionMethod` | `'ip_device_match'` (link-click matching) or `'manual_entry'` (a code the user applied) |
| `clickedAt` | When the link was clicked, or the code applied |
| `message` | A short explanation, for logs |

Attribution is decided once per install and stored on the device; later calls return the stored answer without a request. Only a failed request is retried, on the next call. A reinstall starts over.

`checkAttribution` is fail-soft: on a network or server error it returns `attributed: false` and stores nothing. Link-click matching only counts taps from the last 72 hours — see [attribution](https://docs.influ.to/advanced/attribution.md). To show referred users a better offer, see [Reward referred users](https://docs.influ.to/guides/referral-offers.md).

## Identify the user

Call `identifyUser` as soon as you know who the user is, with the same ID your purchases are keyed on — for RevenueCat, the app user ID:

```dart
await InfluTo.instance.identifyUser(await Purchases.appUserID);
```

It matters for three things: InfluTo uses it to credit a RevenueCat purchase when the `influto_code` attribute didn't make it, `checkAccess` uses it for free-access codes, and `reportPurchase` sends it by default. Call it once per sign-in, ideally in the user's first session — not from `build`.

## Track events

```dart
await InfluTo.instance.trackEvent(TrackEventOptions(
  eventType: 'paywall_viewed',
  appUserId: userId,
  properties: {'placement': 'onboarding'},
));
```

Events show on **Real-Time Events** and help you read the funnel. They never create conversions or commission — only validated purchases do. Every call gets an event ID, so an accidental double call counts once. For `trial_started`, `subscription_purchased` and `subscription_renewed` the ID is derived from the event, user and properties, so the same event counts once even across launches; include something that changes per occurrence (a transaction ID, say) in `properties` when the event can repeat. For your own once-only events, pass `eventId`.

## Let users type a code

```dart
// Validate + apply a code the user typed
final result = await InfluTo.instance.applyCode('FITGURU30');
if (result.valid && result.applied == true) {
  // Unlock the offer
}

// Or the ready-made widget: ReferralCodeInput(onApplied: (result) { … })
// Free-access codes (after identifyUser): (await setReferralCode(code)).grantsAccess
// == true → unlock premium, and gate premium on (await checkAccess()).hasAccess.
```

`applyCode(code, appUserId: …)` validates the code and applies it if it's valid; the result's `applied` tells you whether it was applied. Codes are trimmed and uppercased for you. An invalid code comes back with `valid: false` and an `errorCode`: `INVALID_FORMAT`, `CODE_NOT_FOUND`, `CODE_EXPIRED` or `NETWORK_ERROR`. If you build your own field, write your own copy: `message` and `influencer` can contain the creator's personal name.

The ready-made field is the `ReferralCodeInput` widget (Material). It validates as the user types and applies the code when they tap the button:

```dart
ReferralCodeInput(
  appUserId: userId,
  onApplied: (result) { /* the code is applied — unlock the offer */ },
)
```

| Parameter | Default | Notes |
|---|---|---|
| `appUserId` | identified user | The user to bind the code to; free-access codes need one |
| `autoPrefill` / `autoValidate` | `true` / `false` | Pre-fill the code from a link-attributed install, and validate it right away |
| `showCampaignName` / `showReferrerName` | `false` / `false` | Show a creator's name only with their consent |
| `title`, `placeholder`, `applyLabel`, `validMessage`, `invalidMessage` | — | Texts, for translation |
| `onValidated`, `onApplied` | — | Called after each validation, and after the code is applied |

More on the UX: [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md). All parameters: [UI components](https://docs.influ.to/reference/ui.md).

## Purchases

InfluTo only pays commission on purchases it has verified with the store. Choose exactly one path per platform — see [Choose a validation path](https://docs.influ.to/integrations.md).

### RevenueCat

Pass a `revenueCatHook`, as in the startup example above. When `checkAttribution` finds a referral, or a code is applied, the SDK calls it with `influto_code` (the code) and `influto_referral` (the string `"true"`). Then connect the webhook — see [RevenueCat](https://docs.influ.to/integrations/revenuecat.md).

> [!IMPORTANT]
> Without the hook, nothing sets the attribute in Flutter. The SDK calls it once, when the referral is found, so configure RevenueCat before `checkAttribution`, and call `identifyUser` with the RevenueCat app user ID as the fallback.

### Store-direct with influto_iap

Create one `InfluToPurchaseObserver` and enable it after `initialize` has finished:

```dart
import 'package:influto_iap/influto_iap.dart';

final observer = InfluToPurchaseObserver(
  oneTimeProductIds: {'coins_100', 'remove_ads'}, // Android one-time products; omit if you only sell subscriptions
);
final sync = await observer.enable(); // listens for new purchases + back-fills existing ones
```

The observer only runs when the app is set to store-direct in **Settings → Validation** and `autoCapture` is `true`; otherwise `enable()` does nothing, so the same build is safe on RevenueCat apps. Each purchase is reported once. `enable()` returns a `PurchaseSyncResult` with `fetched`, `sent` and `failed` counts; `syncExisting()`, `disable()` and `dispose()` are there for manual control.

What the observer does in your app:

- It completes pending purchases (`completePurchase`), so the store doesn't redeliver or refund them. Deliver content from your own `purchaseStream` listener as usual.
- The back-fill calls `restorePurchases()`, so your own listener also sees `restored` purchases at startup. Call `enable(backSync: false)` if you don't want that.
- On iOS it switches `in_app_purchase` to StoreKit 2, which store-direct needs.

To report purchases yourself instead, set `autoCapture: false`, skip the observer, and call `reportPurchase`:

```dart
// Store-direct only (no RevenueCat). For automatic capture add influto_iap and
// call InfluToPurchaseObserver().enable() after initialize(). Or report manually:
await InfluTo.instance.reportPurchase(
  platform: 'ios',                 // or 'android'
  signedTransaction: jws,          // iOS: StoreKit 2 JWS
  // purchaseToken: token,         // Android: Play Billing purchaseToken
);
```

- `platform` is required: `'ios'` or `'android'`. On iOS pass the StoreKit 2 signed transaction, `details.verificationData.serverVerificationData` — with `in_app_purchase` on StoreKit 2 (`InAppPurchaseStoreKitPlatform.enableStoreKit2()` makes sure of it); on Android pass `(details as GooglePlayPurchaseDetails).billingClientPurchase.purchaseToken`.
- It throws an `InfluToException`. `retryable` is true for `503` (the exchange rate was briefly unavailable) — retry later; `notConfigured` is true for `400` (the platform isn't set to store-direct yet).
- Android one-time and consumable products need `productId`, plus `price` and `currency` from the product details; without a price the purchase is recorded at $0. A `409` means the purchase isn't in the PURCHASED state yet.

Set-up, credentials and testing: [Store-direct](https://docs.influ.to/integrations/store-direct.md).

## Free-access codes

Free-access codes give a user premium without a purchase. Redeem one with `setReferralCode(code, appUserId: userId)` after `identifyUser`, or pass the user ID — a code with no user is refused. The `SetCodeResult` tells you what happened: `grantsAccess`, `freeAccess`, `entitlement` and `expiresAt`. `applyCode` doesn't return these flags; after it, `result.campaign?.campaignType == 'FREE_ACCESS'` tells you the code was a free-access code.

Gate premium on your store entitlement or InfluTo's answer:

```dart
final premium = entitlementActive || (await InfluTo.instance.checkAccess()).hasAccess;
```

`checkAccess(appUserId: …)` uses the identified user when you don't pass one, caches a positive answer for 5 minutes (across launches too), never caches a negative one, and returns `hasAccess: false` on errors. See [Free access codes](https://docs.influ.to/platform/creator-access-codes.md).

## Verify

After the first successful `initialize`, **Setup & SDK** shows "Integrated — SDK connected" with the platform and SDK version it last saw. With `debug: true` the SDK prints each step, and **Real-Time Events** lists your events and purchases. For the full end-to-end test and the integration status checklist, see [Verify the integration](https://docs.influ.to/integrations/testing.md).

To test attribution again on the same device, `clearAttribution()` forgets the stored attribution, code and user ID. It's for testing only — a reinstall gives a cleaner start.

## Flutter notes

- **One instance.** Everything goes through `InfluTo.instance`; there are no static calls.
- **Order matters**: configure RevenueCat, then `initialize`, then `checkAttribution`; enable the `influto_iap` observer only after `initialize` has finished, or it stays off.
- **`const` configs**: `InfluToConfig` has a `const` constructor, but a closure such as `(attrs) => …` isn't a constant — drop `const` when you pass a `revenueCatHook`.
- **No automatic RevenueCat tagging.** Unlike React Native, Flutter needs the `revenueCatHook`.
- **Android one-time products** go in the observer's `oneTimeProductIds`, not in `InfluToConfig`.

---

<!-- https://docs.influ.to/sdk/web -->
# Add InfluTo to a Capacitor, Ionic, Cordova or web app

> Use @influto/web in Capacitor, Ionic, Cordova, PWAs and browsers — capture referral links, accept typed codes, and connect RevenueCat or store purchases.

`@influto/web` adds creator attribution to any app whose code runs in a WebView or a browser: Capacitor (including Ionic React, Angular and Vue), Apache Cordova, installed PWAs, Trusted Web Activities and plain web apps. It follows the same contract as the native SDKs, and adds web-only ways to pick up a referral exactly: the launch URL, deep links, and the Google Play Install Referrer. Plan for an afternoon; most of it goes into the purchase side.

| | |
|---|---|
| Package | `@influto/web`, with subpaths `/capacitor`, `/cordova`, `/pwa`, `/revenuecat` and `/react` |
| Latest version | 1.0.1 |
| Registry | [npm](https://www.npmjs.com/package/@influto/web) |
| Runtimes | Capacitor / Ionic, Cordova, PWAs and TWAs, browsers — any ES2019 browser or WebView |
| Builds | ESM, CommonJS, and a script-tag build |
| Dependencies | None. React 17+ only if you use `@influto/web/react` |

## Install

```bash
npm install @influto/web
# Capacitor / Ionic apps (device info, storage, deep links):
npm install @capacitor/device @capacitor/preferences @capacitor/app
```

The Capacitor plugins are optional but recommended: `@capacitor/device` for device details, `@capacitor/preferences` for storage that survives WebView resets, `@capacitor/app` for deep links. Run `npx cap sync` after adding them. Missing plugins fall back to browser defaults.

No bundler? Load `https://cdn.jsdelivr.net/npm/@influto/web@1/dist/index.global.js` with a `<script>` tag and use `window.InfluTo`.

## Initialize

```ts
import InfluTo from '@influto/web';
import { capacitorAdapters } from '@influto/web/capacitor'; // Capacitor / Ionic only

// Call once at startup (Capacitor: after platform ready; PWA: on page load)
await InfluTo.initialize({
  apiKey: 'YOUR_API_KEY',
  appVersion: '1.2.3',
  ...(await capacitorAdapters()),   // omit in a plain PWA / browser
  // RevenueCat apps: revenueCat: revenueCatCapacitor(Purchases)  (from '@influto/web/revenuecat')
});
```

Call `initialize` once, at the app root, and wait for it before calling anything else:

| Runtime | When |
|---|---|
| Capacitor / Ionic | At app start, after the platform is ready — not inside an Ionic page, which can be cached and re-entered |
| Cordova | After `deviceready`: `await whenDeviceReady()` from `@influto/web/cordova` first |
| PWA / browser | On page load |

`initialize` throws when it fails — a wrong key, no network — with an `InfluToApiError` (`status`, `body`) for API errors. Catch it, log it, and carry on: the next launch tries again. If it hasn't succeeded, `checkAttribution` and `reportPurchase` throw "not initialized". It resolves to the app's init result (also available later from `getInitResult()`). A typical Capacitor startup, in order:

```ts file="influto.ts"
import InfluTo from '@influto/web';
import { capacitorAdapters, listenForCapacitorLaunchUrls } from '@influto/web/capacitor';
import { revenueCatCapacitor } from '@influto/web/revenuecat';
import { Purchases } from '@revenuecat/purchases-capacitor';

export async function startInfluTo() {
  await Purchases.configure({ apiKey: 'appl_…' }); // RevenueCat apps: configure it first
  try {
    await InfluTo.initialize({
      apiKey: import.meta.env.VITE_INFLUTO_API_KEY,
      appVersion: '1.4.0',
      ...(await capacitorAdapters()),
      revenueCat: revenueCatCapacitor(Purchases),
    });
  } catch (error) {
    console.warn('InfluTo initialize failed', error); // retried on the next launch
    return;
  }
  await listenForCapacitorLaunchUrls(InfluTo); // deep links → referral claim
  const attribution = await InfluTo.checkAttribution();
  const { appUserID } = await Purchases.getAppUserID();
  await InfluTo.identifyUser(appUserID);
}
```

The API key starts with `it_` and is on **Setup & SDK**; one key works for development and production. Keep it out of committed source — for example in a gitignored `.env.local` read through your bundler.

| Option | Default | What it does |
|---|---|---|
| `apiKey` | required | The app's SDK key (`it_…`) |
| `debug` | `false` | Logs `[InfluTo]` lines to the console |
| `appVersion` | `"unknown"` | Your app version, sent with the startup call |
| `runtime` | detected | `capacitor`, `cordova`, `twa`, `pwa` or `browser` |
| `storage`, `device`, `http` | `localStorage`, browser detection, `fetch` | Adapters; `capacitorAdapters()` and `cordovaAdapters()` fill `storage` / `device` / `runtime` for you |
| `revenueCat` | none | RevenueCat binding — see [Purchases](#purchases) |
| `captureLaunchCode` | `true` | Read `influto_code` / `influto_click` from the page URL at startup |
| `cleanUrl` | `true` | Remove the `influto_*` parameters from the address bar afterwards |
| `purchaseSource` | none | Store-direct apps: where purchases come from — see [Purchases](#purchases) |
| `autoCapture` | `true` | Report purchases from `purchaseSource` automatically |
| `oneTimeProductIds` | none | Your Android one-time and consumable product IDs |

## Detect referred users

```ts
const attribution = await InfluTo.checkAttribution();
if (attribution.attributed) {
  // User came from a referral — show a special offer / extended trial.
  // With a RevenueCat binding the SDK also sets influto_code + influto_referral.
  console.log('Referred by', attribution.referralCode);
}

// Web deep links: referral links send web visitors to your app URL with
// ?influto_code=…&influto_click=… — the SDK claims them automatically.
```

| Field | Meaning |
|---|---|
| `attributed` | `true` when the install came from a creator's link or code |
| `referralCode` | The creator's code, uppercase |
| `attributionMethod` | `link_param` (the link carried the code into the app), `ip_device_match` (link-click matching) or `manual_entry` (a code the user applied) |
| `clickedAt`, `clickId` | When the link was clicked, and which click was claimed |
| `message` | A short explanation, for logs |

Attribution is decided once per install and stored; later calls return the stored answer. Only a failed request is retried. `checkAttribution` is fail-soft: on a network or server error it returns `attributed: false` and stores nothing. In React, `useInfluToAttribution(enabled)` from `@influto/web/react` returns `{ loading, attribution, error, refresh }`; pass `enabled = false` until `initialize` has resolved.

The web SDK can claim a referral exactly, from the code the link carries, in three ways. A code picked up later re-opens an earlier "organic" answer on the next `checkAttribution` call; an attributed install keeps its creator. Without a carried code, InfluTo falls back to link-click matching within 72 hours — see [attribution](https://docs.influ.to/advanced/attribution.md).

### The launch URL (PWAs and web apps)

Set **Settings → General → Web app URL**. Referral links send desktop visitors — and phone visitors when your app has no store listing for their platform — to that URL with `?influto_code=…&influto_click=…` appended. `initialize` reads both from the query or a hash-router fragment, stores them, and cleans the address bar.

### Deep links (Capacitor and Cordova)

`listenForCapacitorLaunchUrls(InfluTo)` passes the cold-start URL and every `appUrlOpen` event to the SDK; it returns a function that removes the listener. In Cordova, or with your own handler, call `InfluTo.handleLaunchUrl(url)`. Call either after `initialize` and before `checkAttribution`.

### The Play Install Referrer (Android)

Google Play links from InfluTo carry the code and click in Play's `referrer` parameter. On first launch, read the referrer string with an Install Referrer plugin (`@capgo/capacitor-install-referrer` or `cordova-play-install-referrer`) and hand it over after `initialize`, before `checkAttribution`:

```ts
await InfluTo.captureInstallReferrer(referrer); // the raw referrer string from the plugin
const attribution = await InfluTo.checkAttribution();
```

## Identify the user

Call `identifyUser(appUserId, properties?)` as soon as you know who the user is, with the same ID your purchases are keyed on — for RevenueCat, the app user ID (see the startup example). InfluTo uses it to credit a RevenueCat purchase when the `influto_code` attribute didn't make it; `checkAccess`, `setReferralCode` and `reportPurchase` use it by default. Call it once per sign-in, ideally in the user's first session — not on every render.

## Track events

```ts
await InfluTo.trackEvent({ eventType: 'paywall_viewed', appUserId: userId, properties: { placement: 'onboarding' } });
```

Events show on **Real-Time Events** and never create conversions or commission. Every call gets an event ID, so an accidental double call counts once. For `trial_started`, `subscription_purchased` and `subscription_renewed` the ID is derived from the event, user and properties, so the same event counts once even across launches; include something that changes per occurrence in `properties` when the event can repeat, or pass `eventId` yourself.

## Let users type a code

```ts
// Validate, then apply a code the user typed
const result = await InfluTo.applyCode('FITGURU30');
if (result.valid && result.applied) {
  // Unlock the offer
}

// React / Ionic React: drop in the ready-made field
import { ReferralCodeInput } from '@influto/web/react';
<ReferralCodeInput onCodeApplied={(code) => {/* ... */}} />

// Free-access codes: (await InfluTo.setReferralCode(code)).grantsAccess → unlock
// premium, and gate premium on (await InfluTo.checkAccess()).hasAccess.
```

`applyCode(code, appUserId?)` validates the code and applies it if it's valid. Codes are trimmed and uppercased for you. An invalid code comes back with `valid: false` and an `error_code`: `INVALID_FORMAT`, `CODE_NOT_FOUND`, `CODE_EXPIRED` or `NETWORK_ERROR`. If you build your own field, write your own copy: `message` and `influencer` can contain the creator's personal name.

`ReferralCodeInput` from `@influto/web/react` is a plain, unstyled form: an input and a button. It pre-fills a link-attributed code and applies the code on submit.

| Prop | Default | Notes |
|---|---|---|
| `onCodeApplied(code, result)` | — | The code was valid and applied |
| `onInvalid(result)` | — | The code was rejected |
| `appUserId` | identified user | The user to bind the code to |
| `prefill` | `true` | Pre-fill from a link-attributed install |
| `showCampaignName` / `showReferrerName` | `false` / `false` | Show a creator's name only with their consent |
| `placeholder`, `buttonLabel` | `'Referral or access code'`, `'Apply'` | Texts, for translation |
| `className`, `style`, `inputClassName`, `buttonClassName` | — | Styling |

Angular, Vue or no framework: build the field yourself on `applyCode`. More on the UX: [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md). All props: [UI components](https://docs.influ.to/reference/ui.md).

## Purchases

InfluTo only pays commission on purchases it has verified with the store. Choose exactly one path per platform — see [Choose a validation path](https://docs.influ.to/integrations.md).

### RevenueCat

Pass a binding as `revenueCat`. When `checkAttribution` finds a referral, or a code is applied, the SDK sets `influto_code` (the code) and `influto_referral` (the string `"true"`) through it. Then connect the webhook — see [RevenueCat](https://docs.influ.to/integrations/revenuecat.md).

| Your RevenueCat SDK | Binding (from `@influto/web/revenuecat`) |
|---|---|
| `@revenuecat/purchases-capacitor` 7.5.10+ | `revenueCatCapacitor(Purchases)` |
| `@revenuecat/purchases-js` 1.4.0+ (Web Billing) | `revenueCatJs(() => Purchases.getSharedInstance())` |
| `cordova-plugin-purchases` | `revenueCatCordova(window.Purchases)` |
| Anything else | A function `(attrs) => …`, or any object with `setAttributes(map)` — wrap it in `revenueCatBinding(obj)` to get retries |

The bindings retry a failed write up to 3 times (options `retries`, `backoffMs`, `onError`). To attach one after `initialize`, call `InfluTo.attachRevenueCat(binding)` — before `checkAttribution`.

> [!IMPORTANT]
> The attribute is written when the referral is found, not later. Configure RevenueCat and attach the binding before `checkAttribution`, and call `identifyUser` with the RevenueCat app user ID as the fallback.

### Store-direct

Pass a purchase source as `purchaseSource`. When the app is set to store-direct in **Settings → Validation** and `autoCapture` isn't `false`, `initialize` starts reporting new purchases and back-fills existing ones, each once.

| Runtime | Purchase plugin | Source |
|---|---|---|
| Capacitor | `@capgo/native-purchases` | `capgoNativePurchasesSource(NativePurchases, { oneTimeProductIds })` from `/capacitor` |
| Cordova | `cordova-plugin-purchase` v13 | `cordovaPurchaseSource(CdvPurchase.store, { oneTimeProductIds })` from `/cordova` |
| TWA on Google Play | Digital Goods API (Chrome 101+) | `digitalGoodsSource({ oneTimeProductIds })` from `/pwa` |

The Digital Goods API has no purchase event, so call `InfluTo.syncExistingPurchases()` after each checkout. `requestPlayBillingPurchase(itemId)` from `/pwa` runs a Play Billing checkout and returns `{ purchaseToken }`, or `null` if the user cancelled. You can also drive capture yourself with `enableAutoPurchaseCapture(source, { backSync, oneTimeProductIds })` and `disableAutoPurchaseCapture()`.

- **iOS** needs the StoreKit 2 signed transaction. `capgoNativePurchasesSource` passes it on; with `cordova-plugin-purchase`, check that your setup exposes one, or iOS reports fail.
- **Android one-time products**: the Capacitor and Cordova sources don't carry a price, and a one-time purchase without a price is recorded at $0. Report those yourself with `price` and `currency`. `digitalGoodsSource` looks the price up.

To report purchases yourself instead, set `autoCapture: false` and call `reportPurchase`:

```ts
// Store-direct only (no RevenueCat). Attach a purchase source and purchases are
// captured automatically — TWA/PWA on Play: digitalGoodsSource(); Capacitor:
// capgoNativePurchasesSource(); Cordova: cordovaPurchaseSource(). Or report manually:
await InfluTo.reportPurchase({
  platform: 'android',             // or 'ios'
  purchaseToken: token,            // Android: Play Billing purchaseToken
  // signedTransaction: jws,       // iOS: StoreKit 2 JWS
});
```

- In a browser or PWA, always pass `platform` (`'ios'` or `'android'`); the SDK refuses to guess when it detects `web`.
- It throws an `InfluToApiError`. `503`: the exchange rate was briefly unavailable — retry later. `400`: the platform isn't set to store-direct yet. `409`: an Android one-time purchase isn't in the PURCHASED state yet.
- Android one-time products need `productId`, plus `price` and `currency`.

Set-up, credentials and testing: [Store-direct](https://docs.influ.to/integrations/store-direct.md).

## Free-access codes

Free-access codes give a user premium without a purchase. Redeem one with `setReferralCode(code, appUserId?)`; it uses the identified user when you don't pass one, and a code with no user is refused. The result tells you what happened: `grantsAccess`, `freeAccess`, `entitlement` and `expiresAt`. `applyCode` doesn't return these flags; after it, `result.campaign?.campaign_type === 'FREE_ACCESS'` tells you the code was a free-access code.

Gate premium on your store entitlement or InfluTo's answer: `entitlementActive || (await InfluTo.checkAccess()).hasAccess`. `checkAccess` caches a positive answer for 5 minutes, never caches a negative one, and returns `hasAccess: false` on errors. See [Free access codes](https://docs.influ.to/platform/creator-access-codes.md).

## Verify

After the first successful `initialize`, **Setup & SDK** shows "Integrated — SDK connected" with the platform, `@influto/web` and the SDK version it last saw. With `debug: true` the SDK logs each step, and **Real-Time Events** lists your events and purchases. For the full end-to-end test and the integration status checklist, see [Verify the integration](https://docs.influ.to/integrations/testing.md). To test attribution again, `clearAttribution()` forgets the stored attribution, code and launch code.

## Platform notes

### Capacitor and Ionic

- With `@capacitor/preferences` installed, `capacitorAdapters()` stores the SDK's state there. WebView `localStorage` is wiped when `androidScheme` or `iosScheme` changes; pass `{ usePreferences: false }` to keep `localStorage` anyway.
- The reported platform is the native OS (`ios` or `android`).
- In a web dev build (`ionic serve`) the RevenueCat Capacitor plugin is a stand-in, so attribute writes do nothing there. Test on a device.

### Cordova

- A fresh Cordova template blocks the API twice: add `<access origin="https://influ.to" />` to `config.xml` and `connect-src https://influ.to` to the Content-Security-Policy meta tag.
- Start with `await whenDeviceReady()` and pass `...cordovaAdapters()` to `initialize`; storage stays in `localStorage`.
- RevenueCat has deprecated its Cordova plugin. For a new app, prefer Capacitor.

### PWAs, TWAs and web apps

- Set the **Web app URL** so referral links can hand the code to your app.
- The platform comes from the user agent the same way InfluTo classifies a click: phones are `ios` or `android`, everything else `web`.
- A TWA on Google Play can sell through Play Billing (`digitalGoodsSource()`); web checkout through RevenueCat Web Billing works with `revenueCatJs()`. iOS home-screen web apps can't sell in-app purchases, but attribution still works.
- `isStandalone()` and `hasDigitalGoods()` from `/pwa` tell you whether you're running installed and whether Play Billing is available.

### Script tag

The script-tag build contains the core SDK only; the subpath helpers need a bundler. Pass `revenueCat` as a plain function that calls your RevenueCat SDK's `setAttributes`.

---

<!-- https://docs.influ.to/integrations -->
# Choose a purchase validation path

> InfluTo verifies every purchase before it pays commission — through your RevenueCat webhook or directly with Apple and Google. How to choose, and why never both.

InfluTo never pays commission on a purchase it hasn't verified with the store. You connect that verification in one of two ways, chosen per platform in **Settings → Validation**: RevenueCat, or store-direct. Use exactly one per platform — two paths would report every purchase twice.

## The short answer

- **You use RevenueCat** → [RevenueCat](https://docs.influ.to/integrations/revenuecat.md). Nothing to call at purchase time; RevenueCat sends InfluTo every purchase, renewal and refund.
- **You don't use RevenueCat** → [Store-direct](https://docs.influ.to/integrations/store-direct.md). The SDK sends the store's signed proof of each purchase, and InfluTo checks it with Apple or Google.

## Side by side

| | RevenueCat | Store-direct |
|---|---|---|
| You need | A RevenueCat project for the app | An App Store Server API key (`.p8`) and/or a Google Play service account |
| How InfluTo hears about purchases | RevenueCat's webhook, server to server | The SDK reports each purchase; InfluTo re-checks subscriptions with the stores every hour |
| Code in your app | Let the SDK tag the RevenueCat subscriber with the referral code | Usually none — automatic capture, or `reportPurchase` if you prefer |
| Setup in the dashboard | **Setup & SDK → Webhook**: connect automatically with a RevenueCat v2 secret key, or paste the URL and secret into RevenueCat | **Settings → Validation**: upload the credentials and wait for the green check |
| Renewals and cancellations | From RevenueCat events | From the stores (hourly check; Google also via real-time notifications) |
| Refunds reversed | Yes, from RevenueCat refund events | Subscriptions on both stores and Google Play one-time purchases |

> [!WARNING]
> Never wire both on the same platform. If the app uses RevenueCat, leave store-direct off. If it's store-direct, don't also send RevenueCat webhooks for that platform.

## Mixing platforms

The choice is per platform. An app can validate iOS directly with Apple and Android through RevenueCat, for example. The SDK learns the setting from InfluTo at startup, so automatic purchase capture only runs on platforms set to store-direct.

## Testing either path

Sandbox and TestFlight purchases flow through the same pipeline and show up in **Real-Time Events**, but they never move money or change stats. How to run a full test: [Verify the integration](https://docs.influ.to/integrations/testing.md).

---

<!-- https://docs.influ.to/integrations/revenuecat -->
# Validate purchases with RevenueCat

> Connect InfluTo to RevenueCat — tag subscribers with the referral code from the SDK, add the webhook automatically or by hand, and test that purchases are attributed.

Use this path if your app already sells through RevenueCat. The InfluTo SDK writes the referral code onto the RevenueCat subscriber, RevenueCat sends every purchase, renewal and refund to InfluTo's webhook, and InfluTo turns the attributed ones into commissions. Your app calls nothing at purchase time.

Not using RevenueCat? Use [store-direct](https://docs.influ.to/integrations/store-direct.md) instead — never both on the same platform.

## How it works

1. A referred user opens your app. `checkAttribution` (or a code they type) gives the SDK the creator's code.
2. The SDK sets two subscriber attributes in RevenueCat: `influto_code` (for example `MAYA`) and `influto_referral` (the string `"true"`).
3. The user buys. RevenueCat sends the event to `https://influ.to/api/webhooks/revenuecat/{app_id}`.
4. InfluTo reads `influto_code` from the event, finds the creator, and records the conversion. If the attribute is missing, it falls back to the user ID you passed to `identifyUser`.

<!-- steps -->

### Let the SDK tag subscribers

How the SDK reaches RevenueCat depends on the platform. Configure RevenueCat before you call `checkAttribution` or `applyCode`, so the attribute can be written.

<!-- tabs -->
<!-- tab: React Native / Expo -->
Nothing to add. If `react-native-purchases` is installed and configured, the SDK finds it and sets the attributes itself.

```tsx
Purchases.configure({ apiKey: REVENUECAT_API_KEY });
await InfluTo.initialize({ apiKey: INFLUTO_API_KEY });
```
<!-- tab: iOS (Swift) -->
Give the SDK a setter. It calls it with the two attributes.

```swift
var config = InfluToConfig(apiKey: influtoApiKey)
config.revenueCatAttributeSetter = { attrs in
  Purchases.shared.attribution.setAttributes(attrs)
}
try await InfluTo.initialize(config)
```
<!-- tab: Android (Kotlin) -->
The SDK finds the RevenueCat SDK on its own. To be explicit, pass a setter:

```kotlin
InfluTo.initialize(applicationContext, InfluToConfig(
  apiKey = influtoApiKey,
  revenueCatAttributeSetter = { attrs -> Purchases.sharedInstance.setAttributes(attrs) },
))
```
<!-- tab: Flutter (Dart) -->
Pass a hook in the config.

```dart
await InfluTo.instance.initialize(InfluToConfig(
  apiKey: influtoApiKey,
  revenueCatHook: (attrs) => Purchases.setAttributes(attrs),
));
```
<!-- tab: Web / Capacitor / PWA -->
Pass a binding for the RevenueCat SDK you use.

```ts
import { revenueCatCapacitor } from '@influto/web/revenuecat';

await InfluTo.initialize({
  apiKey: INFLUTO_API_KEY,
  ...(await capacitorAdapters()),
  revenueCat: revenueCatCapacitor(Purchases),
  // purchases-js (Web Billing): revenueCat: revenueCatJs(() => Purchases.getSharedInstance())
  // cordova-plugin-purchases:   revenueCat: revenueCatCordova(window.Purchases)
});
```
<!-- /tabs -->

Then, once you know who the user is, call `identifyUser` with their RevenueCat app user ID. It's the fallback InfluTo uses when an event arrives without the attribute.

### Connect the webhook

Open **Setup & SDK → Webhook** in the InfluTo dashboard and pick one of the two ways.

**Automatically (recommended).** Paste a RevenueCat **v2 secret API key** under *Connect RevenueCat automatically*, and InfluTo creates a webhook named "InfluTo" in your RevenueCat project — both environments, all events. Create the key in RevenueCat under your project → **API keys → New secret API key**, version V2, with these permissions:

- Project configuration → Integrations: **Read & write**
- Project configuration → Projects: **Read**
- Customer information → Customers: **Read & write** — only if you also use [free-access codes](https://docs.influ.to/platform/creator-access-codes.md)

If the key can see several projects, InfluTo asks which one belongs to this app.

**By hand.** In RevenueCat, open your project → **Integrations → Webhooks → Add new configuration**:

| Field | Value |
|---|---|
| Name | Anything, for example `InfluTo` |
| Webhook URL | `https://influ.to/api/webhooks/revenuecat/{app_id}` — copy it from **Setup & SDK**, it already contains your app ID |
| Authorization header value | `Bearer rc_webhook_…` — press **Generate secret** on **Setup & SDK** and paste exactly what it shows, including the word `Bearer`. It's shown once. |
| Environment | Both Production and Sandbox |
| Events filter | All apps, all events |

Leave HMAC signing off — InfluTo checks the Authorization header.

### Test it

In RevenueCat, open the webhook's test page and press **Send Test Event**. Within seconds it appears in **Real-Time Events** in InfluTo.

Then run a real sandbox purchase through a referral link, as in the [quick start](https://docs.influ.to/quick-start.md#test-a-referred-purchase), or press **Send Test Webhook** on **Setup & SDK** to push a simulated sandbox purchase through the attribution pipeline. Full checklist: [Verify the integration](https://docs.influ.to/integrations/testing.md).

<!-- /steps -->

## Events InfluTo uses

Leave RevenueCat on "All events". InfluTo acts on these and acknowledges the rest:

| Event | What InfluTo does |
|---|---|
| `INITIAL_PURCHASE` | Records the conversion. A free trial is recorded but earns nothing until it converts to paid. |
| `RENEWAL` | Pays commission again (and turns a converting trial into a paid conversion). |
| `NON_RENEWING_PURCHASE` | Pays commission on a one-time in-app purchase. |
| `PRODUCT_CHANGE` | Notes the new product; the next renewal is paid on its price. |
| `CANCELLATION`, `UNCANCELLATION`, `EXPIRATION` | Track whether the subscription is still active. |
| `REFUND` | Reverses the commission. |
| `BILLING_ISSUE` | Logged only. |
| `TEST` | Confirms the webhook works. |

Purchases from RevenueCat's sandbox, Xcode and local testing environments are recorded for testing but never move money or change stats.

## The subscriber attributes

| Attribute | Value | Used by |
|---|---|---|
| `influto_code` | The creator's code, uppercased | InfluTo — this is what attributes the purchase |
| `influto_referral` | The string `"true"` | You — for RevenueCat targeting or experiments that treat referred users differently ([example](https://docs.influ.to/guides/referral-offers.md)) |

Keep `influto_referral` a string. RevenueCat attributes are strings, and a targeting rule written for `"true"` won't match a boolean.

If your app learns the code some other way — your own deep link, a promo flow — you can set `influto_code` yourself with RevenueCat's `setAttributes`. InfluTo uppercases it.

## Webhook responses

| Status | Meaning |
|---|---|
| `200` | Received. Processing problems are also answered with 200 (and an `error` field) so RevenueCat doesn't retry them — check **Real-Time Events** if a purchase is missing. |
| `401` | The Authorization value doesn't match this app's secret. The response says how to fix it, and **Setup & SDK** shows how many calls were rejected. |
| `404` | Unknown app ID in the URL. |
| `400` | The body isn't valid JSON. |

## When purchases aren't attributed

- **No `influto_code` on the subscriber.** RevenueCat wasn't configured when the SDK tried to tag the user, or (iOS, Flutter, web) the setter, hook or binding isn't passed. Call `identifyUser` as a safety net.
- **The campaign or the creator isn't active.** Codes only attribute while the campaign is active.
- **The user was already attributed.** The first creator who brought a user keeps them; a code typed later doesn't move an existing subscriber.

More causes and fixes: [Troubleshooting](https://docs.influ.to/advanced/troubleshooting.md).

## With an AI agent

The MCP tool `influto_setup_revenuecat` does the automatic connection for you (using the stored v2 key) and falls back to the exact manual steps. See [AI agents](https://docs.influ.to/agents/index.md).

---

<!-- https://docs.influ.to/integrations/store-direct -->
# Validate purchases directly with Apple and Google

> Use InfluTo without RevenueCat — add App Store Server API and Google Play credentials, let the SDK report purchases, and InfluTo verifies each one with the store.

Store-direct is for apps that don't use RevenueCat. The InfluTo SDK sends the store's signed proof of each purchase — a StoreKit 2 transaction on iOS, a Play Billing purchase token on Android — and InfluTo verifies it with Apple or Google before recording a commission. Afterwards InfluTo checks attributed subscriptions with the stores every hour to pick up renewals, cancellations and refunds. You don't need a backend of your own.

Using RevenueCat? Use the [RevenueCat path](https://docs.influ.to/integrations/revenuecat.md) instead — never both on the same platform.

<!-- steps -->

### Add your store credentials

Open **Settings → Validation** for the app. InfluTo only reads from the stores; it never changes anything in your accounts.

**Apple (App Store Server API)**

1. In App Store Connect, open **Users and Access → Integrations → In-App Purchase** and create a key. Download the `.p8` file — Apple lets you download it once.
2. Note the **Issuer ID** and the **Key ID** shown on that page.
3. In InfluTo, upload the `.p8` (drag and drop works; the Key ID is read from the file name when it's Apple's default), enter the Issuer ID and Key ID, and the app's numeric **App Store ID** (needed for production).
4. Choose the **Environment**: *Sandbox* while you test with TestFlight or sandbox testers, *Production* before you release. InfluTo verifies against exactly the environment you pick — a TestFlight purchase sent to an app set to Production fails verification.

The app also needs its bundle ID set (it comes from the store listing when you add the app).

**Google (Play Developer API)**

1. In Google Cloud, enable the **Google Play Android Developer API** and create a service account with a JSON key.
2. In the Play Console, open **Users and permissions**, invite the service account's email, and give it **View financial data, orders, and cancellation survey responses** for the app.
3. Upload the JSON key in InfluTo and press **Save & validate**.

New Google permissions can take up to 48 hours to reach the API. InfluTo shows the check as "propagating" meanwhile.

### Switch the platform to store-direct

When the credential check is green, pick **Apple — direct**, **Google — direct** or **Both stores — direct** as the validation provider. You can't switch before the check passes, and until you do, the SDK's purchase reports are answered with `400` — so it's safe to ship the SDK first.

The choice is per platform: iOS can be store-direct while Android stays on RevenueCat.

### Let the SDK report purchases

On store-direct platforms the SDK captures purchases on its own once you add the platform's capture code. At startup it asks InfluTo whether the platform is store-direct, and only then starts listening — so the same build is safe on RevenueCat apps.

| SDK | To capture automatically |
|---|---|
| iOS | Built in — the SDK observes StoreKit 2 transactions (also report right after each purchase, see below) |
| React Native | Install `expo-iap` or `react-native-iap` |
| Android | Add `to.influ:android-sdk-billing` |
| Flutter | Add `influto_iap` and call `InfluToPurchaseObserver().enable()` after `initialize` |
| Web / Capacitor | Pass a `purchaseSource` — `capgoNativePurchasesSource()`, `cordovaPurchaseSource()` or `digitalGoodsSource()` for Play in a TWA |

Automatic capture also back-fills purchases that happened before it started, and reports each purchase once. Selling one-time products on Android? List their product IDs in `oneTimeProductIds` (React Native, Android, web) so they're validated as one-time purchases rather than subscriptions.

<!-- /steps -->

## Reporting purchases yourself

You can call `reportPurchase` after each successful purchase — instead of automatic capture (set `autoCapture: false`), or alongside it. Reports are de-duplicated on the store's transaction identity, so a purchase reported twice is still counted once.

> [!TIP]
> On iOS, report right after `product.purchase()` succeeds. StoreKit hands purchases made inside your app back to the caller rather than to the background listener, so without the explicit report a purchase is only picked up when the app next starts.

<!-- tabs -->

```tsx title="React Native / Expo"
// Store-direct only (no RevenueCat). With expo-iap or react-native-iap installed,
// purchases are captured automatically on store-direct apps. To report
// manually instead, pass the store-signed proof:
await InfluTo.reportPurchase({
  platform: 'ios',                 // or 'android'
  signedTransaction: jwsString,    // iOS: StoreKit 2 JWS
  // purchaseToken: token,         // Android: Play Billing purchaseToken
});
```

```swift title="iOS (Swift)"
// Store-direct only (no RevenueCat). Report right after a purchase — StoreKit
// doesn't send purchases made in your app to the background listener, and
// reports are de-duplicated, so this is safe alongside auto-capture:
if case .success(let verification) = try await product.purchase() {
  let r = try await InfluTo.reportPurchase(verification: verification)
}
```

```kotlin title="Android (Kotlin)"
// Store-direct only (no RevenueCat). With the android-sdk-billing artifact on the
// classpath, purchases are captured AUTOMATICALLY. To report manually:
InfluTo.reportPurchase(
  purchaseToken = purchase.purchaseToken,
  // productId = "coins_100",  // one-time / consumable products only
)
```

```dart title="Flutter (Dart)"
// Store-direct only (no RevenueCat). For automatic capture add influto_iap and
// call InfluToPurchaseObserver().enable() after initialize(). Or report manually:
await InfluTo.instance.reportPurchase(
  platform: 'ios',                 // or 'android'
  signedTransaction: jws,          // iOS: StoreKit 2 JWS
  // purchaseToken: token,         // Android: Play Billing purchaseToken
);
```

```ts title="Web / Capacitor / PWA"
// Store-direct only (no RevenueCat). Attach a purchase source and purchases are
// captured automatically — TWA/PWA on Play: digitalGoodsSource(); Capacitor:
// capgoNativePurchasesSource(); Cordova: cordovaPurchaseSource(). Or report manually:
await InfluTo.reportPurchase({
  platform: 'android',             // or 'ios'
  purchaseToken: token,            // Android: Play Billing purchaseToken
  // signedTransaction: jws,       // iOS: StoreKit 2 JWS
});
```

<!-- /tabs -->

- `reportPurchase` throws on failure — handle it.
- A `503` means the currency rate wasn't available; retry later. Reports are idempotent, so retrying is safe.
- A `409` on Android means the one-time purchase isn't in the PURCHASED state yet (still pending).
- On iOS, set the purchase's `appAccountToken` with `InfluTo.appAccountToken(forUserID:)` if you want purchases tied to your user ID.

Purchases are de-duplicated on the store's identity — Apple's original transaction ID and Google's purchase token — so the same purchase is never counted twice, whoever reports it.

## What InfluTo handles on the server

- Verifies every reported purchase with Apple or Google before recording it.
- Converts the price to USD at the purchase date's exchange rate; commissions are calculated in USD.
- Checks attributed subscriptions every hour for renewals, cancellations, expirations and refunds.
- Reverses commission on refunded subscriptions and one-time purchases on both stores.

## Test it

1. Set the Apple environment to **Sandbox** and use a TestFlight or sandbox tester account, or a Google Play license tester.
2. Open a referral link, install, launch, buy.
3. Check **Real-Time Events** — the purchase shows as validated and attributed. Sandbox purchases never move money.

Switch Apple back to **Production** before you release. Full checklist: [Verify the integration](https://docs.influ.to/integrations/testing.md).

## With an AI agent

Agents can't receive your keys — credentials always go through a dashboard link you open yourself (`influto_get_credential_upload_link`). After that, `influto_validate_store_credentials` runs the green check and `influto_activate_store_direct` switches the platform over. See [AI agents](https://docs.influ.to/agents/index.md).

---

<!-- https://docs.influ.to/integrations/testing -->
# Verify the integration is live

> Prove your InfluTo integration works before launch — the dashboard checks, an end-to-end sandbox purchase, and the eight-step integration status for scripts and AI agents.

An integration is done when a referred test purchase shows up in InfluTo as attributed to a creator. This page shows three ways to get there: the dashboard, a full test on a device, and the integration-status API that scripts and AI agents use.

## In the dashboard

- **Setup & SDK** confirms the SDK has connected: after your app's first `initialize` it shows the platform and SDK version it last saw.
- **Send Test Webhook** on **Setup & SDK** pushes a simulated sandbox purchase through the attribution pipeline. It needs an active campaign with at least one creator.
- **Real-Time Events** lists SDK events and purchase events as they arrive, with filters, and marks which purchases were attributed and to which code.

## A full test on a device

<!-- steps -->

### Get a referral link

Activate a campaign, then join it with a creator account that isn't a member of your organization (a second email address or a colleague) and copy the referral link — `https://influ.to/{app_slug}/{CODE}`.

### Install through the link

On a test device, open the link, then install your test build. Use the same network for the tap and the first launch: link-click matching works on the tap you just made. Typing the code into your code field works on any network.

### Launch the app

`checkAttribution` should return `attributed: true` and your code. **Real-Time Events** shows the install.

### Make a sandbox purchase

Use a TestFlight or sandbox tester on iOS, or a license tester on Google Play. On store-direct, set the Apple environment to **Sandbox** first. The purchase appears in **Real-Time Events** as attributed to your code.

<!-- /steps -->

Sandbox purchases never move money, never change your stats and never count toward payouts — you can repeat the test as often as you like.

To start over on the same device, call `clearAttribution()` (or reinstall the app).

## The integration status API

For scripts, CI and AI agents, one call rolls everything up:

```bash
curl https://influ.to/api/agent/apps/$APP_ID/integration-status \
  -H "Authorization: Bearer $INFLUTO_AGENT_KEY"
```

Use an agent key (`it_mcp_…`) from **Connect AI Agent** in the dashboard, or an OAuth token from the MCP connection. The app's SDK key (`it_…`) doesn't work here.

The response contains `live`, a `checklist` of eight steps and `next_actions` for whatever is still open:

| Step | Done when |
|---|---|
| `app_created` | Always true for an existing app |
| `campaign_active` | At least one campaign is active — codes don't attribute without one |
| `sdk_initialized` | The SDK has called `initialize` (shows SDK, version and platform) |
| `sdk_event_received` | At least one SDK event arrived |
| `validation_configured` | A purchase-validation path is set up and ready for the enabled platforms |
| `revenuecat_webhook_wired` | The RevenueCat webhook was connected automatically (RevenueCat path only) |
| `purchase_webhook_seen` | At least one purchase event was received |
| `attributed_conversion` | At least one purchase was attributed to a creator — the integration is proven |

Two more endpoints help when something is off:

```bash
# Recent SDK events and purchase events, with attribution flags
curl "https://influ.to/api/agent/apps/$APP_ID/events/recent?environment=SANDBOX&limit=20" \
  -H "Authorization: Bearer $INFLUTO_AGENT_KEY"

# Push a sandbox INITIAL_PURCHASE through the real pipeline
curl -X POST https://influ.to/api/agent/apps/$APP_ID/test-integration \
  -H "Authorization: Bearer $INFLUTO_AGENT_KEY"
```

With the InfluTo MCP connected, the same checks are the tools `influto_integration_status`, `influto_recent_events` and `influto_test_integration`. If anything about the connection itself looks wrong, run `influto_doctor` first.

## If the test fails

| What you see | Likely cause |
|---|---|
| Nothing on **Setup & SDK** or in Real-Time Events | `initialize` didn't run, or the API key is wrong |
| Install shows as organic | Tap and first launch were on different networks, the window passed, or the campaign isn't active — typing the code is the reliable test |
| No purchase events (RevenueCat) | Webhook URL or Authorization value is wrong — **Setup & SDK** shows rejected calls |
| No purchase events (store-direct) | Credentials aren't green yet, or the platform isn't switched to store-direct |
| Purchase arrives but isn't attributed | The subscriber has no `influto_code` (RevenueCat setter or hook missing on iOS, Flutter or web), or the user was already attributed to someone else |

Everything else: [Troubleshooting](https://docs.influ.to/advanced/troubleshooting.md).

---

<!-- https://docs.influ.to/platform/create-app -->
# Create an app in the InfluTo dashboard

> Add your app to InfluTo — organization, store lookup or manual entry, the slug in referral links, the API key, purchase validation and the first settings.

An app is the container InfluTo attributes installs and purchases to. One app covers your iOS and Android versions together and owns the API key your SDK uses, the slug in every referral link, the purchase-validation choice and the settings creators see. Create it once, before you install the SDK.

Your app doesn't need to be live in a store yet — you can add it by bundle ID or package name and connect the store listing after launch.

## Add the app

<!-- steps -->

### Create your organization (first time only)

The first time you add an app, the dashboard asks you to **Create Your Organization**. Enter an **Organization Name** (your company, brand or your own name) and click **Create Organization & Continue**. The organization owns your apps, your [wallet](https://docs.influ.to/platform/wallet.md) and your billing details.

### Open My Apps → Add App

In the sidebar, click **My Apps**, then **Add App**. You can also use **+ Create New App** in the app switcher at the top of the sidebar.

### Find the app in each store

The **Add New App** page has two sections, **iOS App Store** and **Google Play Store**. Both are optional, but you need at least one.

- In each section, paste the app name, the store URL, or the bundle ID / package name, then click **Find iOS App** or **Find Android App** and pick the right result.
- Not released yet? Click **App not released yet? Add it manually** and enter the bundle ID (plus the numeric App Store ID, if you have one) or the package name, then **Use these details**. Store details such as the icon and screenshots fill in after launch.

### Review the combined details

Under **Combined App Details**, check the organization, the app name, the **Short Description** (creators read it on your join pages) and the icon. When an app is on both stores, choose which store's name, description and icon to use, or type your own.

You can leave **Shared Secret (In-App Purchase)** empty. Neither validation path uses it.

### Choose the slug and create

Pick the **App Slug (for referral links)** (rules below), then click **Create App**. The dialog that follows shows your API key and your RevenueCat webhook URL.

<!-- /steps -->

If you already have an app with the same bundle ID or package name, the dashboard asks whether you meant to add a platform to it. Choose **Add platform to …** unless you really want two separate programs — a package name can belong to only one app on InfluTo.

## The app slug

The slug is the first part of every referral link your creators share:

```text
https://influ.to/{app_slug}/{CODE}     e.g. https://influ.to/fitnow/MAYA
```

- 3–20 characters: lowercase letters, numbers and dashes.
- Unique across all of InfluTo. The dashboard checks availability as you type and suggests one from your app name.
- Some words are reserved because they are already routes or language codes, for example `join`, `api`, `dashboard` or `en`.
- It can't be changed later. **Settings → General** shows it read-only, with **Copy URL Pattern**.

## The API key

Every app has one API key. It starts with `it_` and works for both sandbox and production — InfluTo tells test purchases apart from real ones by the store environment, not by the key.

- The SDK sends it on every request. Pass it to `initialize()` — see [Choose an SDK](https://docs.influ.to/sdk.md).
- The success dialog says the key won't be shown again, but you can copy it any time from **Setup & SDK → Your API Key**.
- There are no separate test and live keys.

## Add a platform later

Launching on the other store later? Don't create a second app — attribution, campaigns and creators belong to the app, so both platforms should share one.

Open **Settings → General**. Under **Platforms**, click **Add iOS** or **Add Android**, paste the store URL, bundle ID or package name and click **Look up** (or enter the identifier manually if the app isn't released yet), then **Add platform**.

## Choose how purchases are validated

InfluTo only credits commission for purchases it has verified with the store. Each platform of your app uses exactly one path:

- **RevenueCat** (the default) — RevenueCat sends purchase events to your app's webhook.
- **Store-direct** — InfluTo checks purchases with Apple and Google directly, using your App Store Server API key and a Google Play service account.

Set it in **Settings → Validation** under **How should InfluTo validate purchases?**: **RevenueCat (default)**, **Apple — direct**, **Google — direct** or **Both stores — direct**. Mixing is allowed — for example Apple-direct on iOS while Android stays on RevenueCat. A platform switches to store-direct only after its credentials pass validation (the green check).

Help choosing: [Validate purchases](https://docs.influ.to/integrations.md). Setup guides: [RevenueCat](https://docs.influ.to/integrations/revenuecat.md) · [Store-direct](https://docs.influ.to/integrations/store-direct.md).

## Settings worth setting now

| Setting | Where | What it does |
|---|---|---|
| **Support email for creators** | Settings → Advanced | Shown to creators in their campaign FAQ, and used as the reply-to address on invitation emails, so questions reach you. Empty sends them to InfluTo support. |
| **My app has the ReferralCodeInput UI component** | Settings → Advanced | Tells creators they can share a spoken code. Turn it on once your app has a code field — the ready-made component or your own. Required for creator access codes. See [Referral codes](https://docs.influ.to/guides/referral-codes.md). |
| **Auto-issue creator access codes** + **Unlock duration (days)** | Settings → Advanced | Gives every creator who joins a personal one-time `INFLU-` code that unlocks your app so they can make content. See [Creator access codes](https://docs.influ.to/platform/creator-access-codes.md). |
| **Web app URL** | Settings → General | For PWAs and web apps. Desktop visitors who open a referral link go here with `influto_code` and `influto_click` attached, and `@influto/web` claims the referral. Capacitor and Ionic apps use the store links instead. |
| **App icon, store URLs** | Settings → General | Used on join pages and in the program directory. |
| **Localization** | Settings → Localization | Your app's name, description and tagline in 11 languages for creators. Missing and outdated translations are generated with one button. |

Save the General and Advanced tabs with **Save Changes**. The Validation and Localization tabs save on their own.

### Attribution window

Link-click matching looks back 72 hours, the same for every app — there's nothing to set. Codes typed into your app and links that carry the code into the app aren't limited by it. More in [Attribution](https://docs.influ.to/advanced/attribution.md).

## With an AI agent

An agent connected over MCP can do all of this for you: `influto_provision` creates the organization, app, API key and a first campaign in one call; `influto_check_slug` checks a slug; `influto_update_app` changes the support email, web app URL, manual code entry and creator access codes; `influto_localize_app` translates the app's copy. Store credentials never pass through the agent — it hands you a dashboard link instead. See [Agent tools](https://docs.influ.to/agents/tools.md).

## Next

<!-- cards -->
- [Install the SDK](https://docs.influ.to/sdk.md) — Pick React Native, iOS, Android, Flutter or web, and initialize it with your API key.
- [Validate purchases](https://docs.influ.to/integrations.md) — Connect RevenueCat or the stores directly.
- [Create a campaign](https://docs.influ.to/platform/create-campaign.md) — Set the commission and open the program to creators.
<!-- /cards -->

---

<!-- https://docs.influ.to/platform/create-campaign -->
# Create an affiliate campaign

> Set up a campaign — type, commission, typical plan price, milestone bonuses and translations — then fund and activate it so creators can join and earn.

A campaign is your affiliate program for one app: what creators earn, who may join, and the copy they read before they sign up. An app can run several campaigns, for example an open program and a private one for a few partners. Every new campaign starts as a draft, and goes live when you activate it with a funded wallet.

## Create the campaign

<!-- steps -->

### Open Campaigns → Create Campaign

Select the app in the app switcher, click **Campaigns** in the sidebar, then **Create Campaign**.

### Name and describe it

Enter the **Campaign Name** and a **Description**. Creators read the description on your join page — say what the app does, who it's for and what kind of content works. A public campaign needs a description to be listed in the program directory.

### Pick the campaign type

| Type | Who can join | Join link |
|---|---|---|
| **Public** | Anyone. Listed in the creator marketplace and eligible for the [program directory](#get-listed-in-the-program-directory). | Works |
| **Private** | Anyone who has the link. Not listed anywhere. | Works |
| **Invite Only** | Only creators you invite by email. | Returns "not found" |

You can change the type later in **Campaign Settings**.

### Set the commission

Enter the **Commission Percentage** (default 30, any value from 0 to 100) and choose what it's paid on: **Every payment** (the first one and every renewal while the subscriber stays — the default) or **First purchase only** (one commission per referred user; renewals earn nothing). One-time in-app purchases earn on each purchase under Every payment. A 0% campaign tracks attribution without paying commission, and InfluTo charges no fee on it — useful when you pay a creator outside InfluTo. The maths, the 10% platform fee and the rules for changing the rate later are on [Commissions and fees](https://docs.influ.to/platform/commissions.md).

### Add a typical plan price (optional)

**Typical plan price** and **Billing period** (per week, per month, per year or one-time) power the earnings estimate creators see on your join page. Enter the plan most of your subscribers pick — a $49.99 annual plan is `49.99` per year.

Once the app has at least 10 paid production purchases in the last 180 days, the estimate switches to the plans people actually buy: the period comes from the subscription length and the price from what they paid. The price you entered becomes the fallback. Either way it is display-only and never changes what anyone is paid.

### Add milestone bonuses (optional) and create

Add up to five one-time bonuses (next section), then click **Create Campaign**. The campaign card shows "Draft — not visible to creators yet".

<!-- /steps -->

## Milestone bonuses

A milestone bonus is a one-time reward on top of commission, such as $40 for a creator's first 10 installs. It gives new creators a reason to post early.

| Field | Rule |
|---|---|
| Milestones per campaign | Up to 5 |
| **Metric** | **Installs**, **Trials** or **Paid subscriptions** |
| **Threshold** | 1–100,000 |
| **Bonus amount** | $1–$1,000 |
| **Time limit (days)** | 7–365, counted from when the creator joined the campaign. Empty means no limit. |
| **Max creators** | 1–10,000 creators can earn it. Empty means no cap. Caps your total exposure at max × amount. |
| **Approve automatically** | On: earned bonuses go straight to payout. Off: you review each one. |

How progress is counted:

- **Installs** count only attributed installs from clicks that weren't flagged as suspicious, and never sandbox activity. See [Analytics](https://docs.influ.to/platform/analytics.md).
- **Trials** and **Paid subscriptions** come from verified store purchases.
- Progress adds up across all of a creator's codes in the campaign, and each milestone pays a creator once.

Review earned bonuses on the campaign page under **Bonus awards**: **Approve** or **Void** each one marked "Needs review". Approved bonuses show "Pays next payout" and are paid from your wallet in the next monthly payout run. Bonuses waiting for review or payout block wallet withdrawals.

You can edit milestones later in **Edit Campaign**. Edits don't change bonuses that were already earned.

## Activate, pause and resume

| State | What it means | How to get there |
|---|---|---|
| **Draft** | Not visible to creators. The join page doesn't load and codes don't validate. | Every new campaign |
| **Active** | Creators can join (public and private), codes validate, purchases earn commission. | **Activate Campaign** on the campaign page |
| **Paused** | 72-hour grace period, then new referrals stop earning. | **Pause Campaign**, or automatically when the wallet runs out |
| **Active again** | Back to normal. | **Resume Campaign** — always manual |

**Activating** needs at least $50 in your wallet that isn't reserved for pending commissions. If you're short, the dashboard opens **Fund your creator budget** with an **Add funds** button (the API returns HTTP 402). After you fund the wallet, the Billing page offers **Activate campaign** in one click. See [Wallet and payouts](https://docs.influ.to/platform/wallet.md).

**Pausing** protects creators who are mid-promotion:

- For 72 hours after you pause, purchases by people a creator referred still earn commission. After that, new purchases through the campaign earn nothing.
- Referral links keep sending people to your store listing the whole time, so links already posted never break.
- Codes typed into your app stop validating as soon as the campaign is paused.
- Renewals of subscribers that creators already brought in keep earning at their locked rate.

If your wallet can no longer cover pending commissions, InfluTo pauses your active campaigns the same way. Top up, then resume each campaign yourself.

**Deleting** happens in **Campaign Settings → Danger Zone**. A draft is deleted immediately. Any other campaign must be paused, have no active creators (use **Terminate Partnership** on each), and the last termination must be at least three days old. Historical data is kept.

## Campaign settings

On the campaign page:

- **Campaign Settings** — **Campaign Type**, **Commission Percentage** and **Accepting New Affiliates**. Rate increases apply immediately; decreases are scheduled with 7 days' notice to creators. See [Changing the commission rate](https://docs.influ.to/platform/commissions.md#changing-the-commission-rate).
- **Accepting New Affiliates** — turn it off to stop new sign-ups through the join link and hide the campaign from the marketplace and the directory. Invitations still work, and existing creators are unaffected.
- **Edit Campaign** — name, description, typical plan price, codes per creator (how many referral codes one creator can hold for the app; default 5, up to 100), milestones and translations.

## Tracking campaigns

A tracking campaign holds your own codes — one per Facebook group, social account, landing page or printed QR code — to see which channel brings installs and sales. Its codes:

- count clicks, installs, trials, paid subscriptions and revenue for that channel, like a creator's code;
- pay no commission and no platform fee, and need no wallet balance;
- give the user no referral benefit: InfluTo reports them with `code_kind: "tracking"` (see the [HTTP API](https://docs.influ.to/reference/http-api.md#post-sdkset-referral-code)), so your app can skip referral offers for them;
- can't be joined or given to creators.

Create one with **Create Campaign → Tracking codes**, activate it, then add codes on the campaign page under **Tracking codes** (one per line; 4–20 letters, digits, `_` or `-`; up to 100 at a time). A code that's taken by a creator or a free-access code — or differs only in lookalike characters (`O`/`0`, `I`/`L`/`1`) — is refused with the reason. Share each code's link, `influ.to/{app_slug}/{CODE}`, and add `?s=` per post (`influ.to/{app_slug}/{CODE}?s=post-12`). See the results in **Analytics → By group / tag** with **Code** or **Code → post**.

Agents: `influto_create_campaign` with `code_kind: "tracking"`, then `influto_create_tracking_codes`.

## Localization

Creators see your campaign in their own language. InfluTo supports 11: English, Czech, Russian, Spanish, German, Hungarian, Ukrainian, Portuguese (Brazil), Polish, French and Italian.

- Open **Edit Campaign → Translations**. One button translates the missing languages and updates outdated ones; **Retranslate all** regenerates every language from the current English.
- Translations are stale-aware. Each language remembers the English it was made from. When you edit the English name or description, existing translations are marked outdated — they stay live until you update them. A translation you edit by hand counts as up to date.
- Join links take `?lang=`, for example `https://influ.to/join/{org}/{slug}?lang=cs`. Invitation emails go out in five of these languages; see [Invite creators](https://docs.influ.to/platform/invite-influencers.md).

## Get listed in the program directory

[influ.to/affiliate-programs](https://influ.to/affiliate-programs) is InfluTo's public directory of affiliate programs, which search engines index. A campaign is listed when all of these are true:

- it is **Public** and **Active**,
- it is **Accepting New Affiliates**,
- the app has an icon,
- the campaign has a description.

Each app is listed once. If several campaigns qualify, the directory shows the one with the highest commission, then the most active creators, then the newest. The others stay joinable by link but aren't indexed. Private and invite-only campaigns are never listed, and their join pages are not indexed.

## With an AI agent

| Task | Tool |
|---|---|
| Create a campaign (as a draft) | `influto_create_campaign` |
| Activate or pause | `influto_set_campaign_status` — returns 402 when the wallet is short; `influto_get_wallet_topup_link` gives you the funding link |
| Change name, description, rate, price, milestones, translations | `influto_update_campaign` (`name_i18n`, `description_i18n`, `ugc_ideas_i18n`) |
| Read the campaign, including `pricing` (`source: observed` or `declared`) | `influto_get_campaign` |
| Translate the copy | `influto_localize_campaign` |
| Review bonuses | `influto_list_bonus_awards`, `influto_review_bonus_award` |

Agents follow the same rules as the dashboard, including the 7-day notice for rate decreases. See [Agent tools](https://docs.influ.to/agents/tools.md).

## Next

<!-- cards -->
- [Fund your wallet](https://docs.influ.to/platform/wallet.md) — Top up from $50 and activate the campaign.
- [Invite creators](https://docs.influ.to/platform/invite-influencers.md) — Share the join link or send invitations.
- [Commissions and fees](https://docs.influ.to/platform/commissions.md) — What a purchase costs you and what the creator earns.
<!-- /cards -->

---

<!-- https://docs.influ.to/platform/invite-influencers -->
# Invite creators to your campaign

> Bring creators into a campaign — share the join link, send email invitations from the dashboard or in bulk through an AI agent, and know the limits that apply.

Creators reach your campaign in three ways: they open your join link and sign up themselves, they accept an email invitation from you, or you invite them from the InfluTo marketplace. Whichever way they come, each creator ends up with a personal referral code and link for your app. (The dashboard calls creators "affiliates" or "influencers".)

| Way in | Campaign types | Limit |
|---|---|---|
| **Join link** | Public, Private | None — share it as widely as you like |
| **Email invitation** | All | 100 per organization per 24 hours |
| **Marketplace invitation** | All | 1 open invitation per $20 of unreserved wallet balance |

Inviting by email or from the marketplace needs a funded wallet; the join link needs an active campaign. See [Wallet and payouts](https://docs.influ.to/platform/wallet.md).

## Share the join link

Public and private campaigns have a join page:

```text
https://influ.to/join/{org}/{campaign_slug}
https://influ.to/join/{org}/{campaign_slug}?lang=cs
```

`{org}` is a six-character ID for your organization, so you don't need to build the URL yourself: open the campaign and copy it from **Public Invitation Link** (or **Unlisted Invitation Link** on a private campaign) with **Copy Link**. Add `?lang=` with any of the 11 supported languages to open the page in that language.

- The page works only while the campaign is **Active**. Invite-only campaigns have no join page — the link returns "not found".
- Pasted into a chat or social post, the link unfurls into a preview card with the campaign name, app icon and commission.
- Turn off **Accepting New Affiliates** in **Campaign Settings** to stop new sign-ups without breaking existing creators' links.

What creators see on the join page: your app's name, icon, description and store listing; the commission percentage and any scheduled rate change; an earnings estimate from your typical plan price or real purchases; milestone bonuses; and up to six featured examples from your [Assets](https://influ.to/dashboard/assets) library (mark them with the **Feature** star on the Assets page).

A creator who joins is in immediately — there is no approval queue. Their referral code is normally the one they picked when they signed up to InfluTo; if that's already taken in your app, InfluTo generates one. You can't join your own organization's campaigns as a creator.

## Invite by email from the dashboard

<!-- steps -->

### Open the invite form

Open the campaign and, under **Campaign Affiliates**, click **Invite Specific Affiliate**. Or go to **Affiliates → Invite Affiliate** and pick the campaign.

### Enter the creator's details

Fill in **First name**, **Last name** and **Email**. Optionally add a **personal note** (it goes into the invitation email) and a **custom commission** for this creator — leave it empty to use the campaign's rate. Then click **Invite**.

### The creator accepts

They get an email with an accept link, sign up or sign in, and choose their own referral code. Until they do, the campaign shows "Awaiting creator's code" for them.

<!-- /steps -->

Good to know:

- Invitation emails are sent in English, Czech, Russian, Spanish or German. From the dashboard, the email uses your account language if it's one of those five, otherwise English.
- If the creator already promotes this app in another of your campaigns, the dashboard asks you to confirm (**Invite anyway**). They then pick a second, different code — codes are unique per app, and a creator can hold at most five codes for one app (more if the campaign's **Codes per creator** allows it).
- Sending needs at least $50 in your wallet that isn't reserved for pending commissions. If you're short, the dashboard asks you to fund the wallet first (HTTP 402).
- Your organization can send 100 email invitations in any rolling 24 hours. After that the API returns HTTP 429 — share the join link instead, or try again later.

## Invite with an AI agent

An agent connected over MCP can invite one creator or a whole list:

- `influto_invite_creator` — one invitation, with an optional personal note (`message`), a `custom_commission_percentage` for this creator, and the email `language` (`en`, `cs`, `ru`, `es` or `de`).
- `influto_invite_creators_batch` — up to 500 invitations per call, for example from a CSV. Each row takes an email and optionally a name, note, language and custom rate; `default_message` fills in rows without a note. Rows are processed one by one: duplicates are skipped, and the batch stops cleanly when the daily email limit or marketplace capacity runs out, reporting each row's status.
- `influto_list_invitations` tracks who has accepted; `influto_get_join_link` returns the join link and warns when it isn't shareable yet.

A custom rate replaces the campaign rate for that creator. See [Per-creator rates](https://docs.influ.to/platform/commissions.md#per-creator-rates). Tool details: [Agent tools](https://docs.influ.to/agents/tools.md).

## Invite from the marketplace

**Marketplace** lists creators who are already on InfluTo. Select one of your active campaigns, then click **Invite** on a creator's card.

Marketplace invitations are backed by your wallet: you can have one open marketplace invitation (pending or accepted) for every $20 of unreserved balance. With less than $20 available the dashboard asks you to fund the wallet (402); when every slot is in use it returns 429. Withdrawing a pending marketplace invitation frees its slot right away.

## Limits at a glance

| Limit | Value | When you hit it |
|---|---|---|
| Email invitations | 100 per organization, rolling 24 hours | HTTP 429 |
| Marketplace invitations | 1 open invitation per $20 of unreserved balance | 402 (none available) or 429 (all in use) |
| Wallet for email invitations | $50 not reserved for pending commissions | HTTP 402 |
| Agent batch | 500 invitations per call | HTTP 400 |
| Codes per creator per app | 5 | HTTP 400 |
| Join link sign-ups | No limit | — |

## What each creator gets

- **A referral code**, 4–20 characters: letters, digits, `_` and `-`. Codes are stored in uppercase and are unique within your app. Reserved words (`ADMIN`, `TEST`, `API`, `SYSTEM`, `NULL`, `ROOT`, `DELETE`, `REMOVE`) and anything starting with `INFLU-` are refused.
- **A referral link** — `https://influ.to/{app_slug}/{CODE}` — and a QR code for it in their InfluTo dashboard. On a phone the link opens the store for that phone's platform. On a desktop it opens your web app URL with the code attached if you set one, otherwise a store page. Adding `?store=ios` or `?store=android` forces a store.
- **Tracking tags on the link (optional)** — one code can be posted in many places and still be measured per place. The creator adds a short tag for each place: `https://influ.to/{app_slug}/{CODE}?s=fb-hu-keto` for one Facebook group, `?s=fb-hu-vegan` for the next. `s` is short for `sub1`; `s2` sets a second tag (`sub2`); standard UTM tags (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`) work too. Tags don't change attribution or commission. On Android they also go to Google Play in the install referrer, after the code; a web app URL receives them as query parameters. You see the results under **Analytics → By group / tag** — see [Results per group or post](https://docs.influ.to/platform/analytics.md#results-per-group-or-post).
- **Optionally, a creator access code** (`INFLU-` followed by five digits) that unlocks your app so they can make content. You turn this on per app — see [Creator access codes](https://docs.influ.to/platform/creator-access-codes.md).
- **Monthly payouts** of their commission through Stripe — see [Wallet and payouts](https://docs.influ.to/platform/wallet.md#how-creators-get-paid).

A creator's code works in your app as soon as they've picked it, because the SDK checks codes with InfluTo's server. You don't need to ship an app update for new creators.

## Withdraw an invitation or end a partnership

- **Pending invitation:** in the campaign's **Campaign Affiliates** table, open the creator and click **Cancel Invite**. An agent can do the same with `influto_withdraw_invitation`, which only works on invitations that haven't been accepted.
- **Active creator:** open the creator and click **Terminate Partnership**, with an optional reason. The creator is notified by email. Agents can't terminate partnerships.

## Next

<!-- cards -->
- [Creator access codes](https://docs.influ.to/platform/creator-access-codes.md) — Let creators use your premium features while they make content.
- [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md) — Credit creators whose audience hears the code instead of tapping a link.
- [Analytics](https://docs.influ.to/platform/analytics.md) — See which creators drive installs and subscribers.
<!-- /cards -->

---

<!-- https://docs.influ.to/platform/creator-access-codes -->
# Give creators and partners free access with codes

> Unlock premium without a purchase — automatic INFLU- codes for creators, your own free-access codes for press, testers and partners (one at a time or hundreds at once), and the checkAccess gate.

Creators make better content when they can use your premium features. Free-access codes unlock your app without a purchase: InfluTo can issue one to every creator who joins, and you can create your own for press, partners or support. People redeem them in the same code field your app uses for referral codes, and your app asks InfluTo whether the user has access.

| | Creator access code | Your free-access code |
|---|---|---|
| Looks like | `INFLU-` + five digits, e.g. `INFLU-40213` | Anything you choose, e.g. `PRESS2026` |
| Created by | InfluTo, automatically, for each creator who joins | You, on **Free Access Codes** or through an agent |
| Uses | One person | As many as you allow |
| Access length | **Unlock duration (days)**, default 90 | Set per code, 1–3,650 days |
| Earns commission | No | No, unless the code credits a partner |

## Turn on creator access codes

<!-- steps -->

### Make sure your app has a code field

Creators redeem their code in your app, so you need a code field — the ready-made component or your own. See [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md).

### Enable it in Settings → Advanced

Check **My app has the ReferralCodeInput UI component**, then **Auto-issue creator access codes**. The second checkbox stays disabled until the first is on.

### Set the unlock duration

Enter **Unlock duration (days)**, from 1 to 3,650. Empty means 90 days. Click **Save Changes**.

<!-- /steps -->

From then on, every creator who joins one of the app's campaigns or accepts an invitation gets a personal one-time code in their InfluTo dashboard. Creators who joined before you turned it on don't get one automatically. The codes also appear on **Free Access Codes** with a **Creator** badge.

## Create your own codes

Open **Free Access Codes** in the sidebar and click **Create Code**:

| Field | Notes |
|---|---|
| **Code** | 4–20 characters: uppercase letters, digits, `_` and `-`. Codes are unique across all of InfluTo, and the `INFLU-` prefix is reserved. |
| **Campaign (Optional)** | Links the code to a campaign for your own bookkeeping. |
| **Access Duration** | How long each person's access lasts after they redeem, in days, months or years. Default 1 year. It can't be changed after creation. |
| **Expiration Date (Optional)** | The last day the code can be redeemed. People who redeemed it before keep their access until their own access ends. |
| **Max Uses (Optional)** | How many people can redeem it. Empty means unlimited. |
| **Credit a partner (Optional)** | A creator's referral code. Everyone who redeems this code counts as that creator's referral — see [Credit a partner](#credit-a-partner). |
| **Group (Optional)** | A label, such as `testers-october`, to filter and export codes together. |
| **Active** | Inactive codes can't be redeemed. |

In the list you can **Copy** a code, **Copy install link**, **Edit** it (active, blocked, expiration date, max uses, group, partner) or **Delete** it. Filters show active, inactive, blocked and expired codes, and a group when you use groups. **Export CSV** downloads the codes shown by the group filter, with their install links and uses.

Each code also works as an install link: `https://influ.to/{app_slug}/{CODE}`. It sends people to the right store (or to your web app URL on a desktop), and the list shows how many people opened it (link-preview crawlers aren't counted). People still enter the code in your app to unlock. The link earns no commission unless the code credits a partner.

Deactivating, blocking or deleting a code removes access from everyone who redeemed it the next time your app calls `checkAccess()`. Passing the expiration date only stops new redemptions. Grants already mirrored into RevenueCat (below) aren't revoked; they run until their own end date.

Each person's access runs for the code's access duration from their first redemption. Entering the code again restores access inside that window without using another seat; after it, the code is spent for that person.

## Create codes in bulk

For beta testers, giveaways or one code per person in a group, click **Bulk create** on **Free Access Codes**:

| Field | Notes |
|---|---|
| **Number of codes** | 1–500 per batch. |
| **Uses per code** | Default 1: each code works for one person. |
| **Prefix (Optional)** | Up to 8 letters or digits in front of a random part, e.g. `BETA` → `BETA7K2MXQ9P`. Random parts skip lookalike characters (0, O, 1, I, L). |
| **Access Duration** | As for a single code. |
| **Group** | Names the batch, e.g. `testers-october`. |
| **Credit a partner**, **Campaign**, **Expiration Date**, **Note** | Optional, as for a single code. |

When the batch is ready, a CSV with every code and its install link downloads, and the list switches to the new group. **Export CSV** downloads the group again later, with uses so far.

## Credit a partner

A partner — a community admin, a club or a coach who is also a creator in your campaign — can hand out free access in your name and still get the credit. Put their referral code in **Credit a partner** when you create the code (or later in **Edit**):

- Everyone who redeems the code counts as the partner's referred user: one install per person, however many times they re-enter the code.
- When someone who got free access later subscribes, the purchase is the partner's, at the partner's commission terms.
- A visit to the code's install link counts as the partner's click. If the app is installed from that link, the SDK hands your app the free-access code (not the partner's) so it can redeem it.
- The partner must be an active creator of this app. If they leave the campaign, new redemptions still grant access but credit nobody.

A creator's own referral code and a free-access code can't be the same, or differ only in lookalike characters (`O`/`0`, `I`/`L`/`1`): whichever is created second is refused.

## Redeem a code in your app

Free-access codes go through the same field as referral codes. The grant comes from `setReferralCode()`: when the code is a free-access code, the result has `freeAccess` and `grantsAccess` set, plus `expiresAt` (and `entitlement` if you use the RevenueCat mirror below). Unlock premium when `grantsAccess` is true.

Always pass the user's ID — the same one you give `identifyUser()` and RevenueCat. Without it the server can't record the grant and the redemption fails.

<!-- tabs -->
```tsx title="React Native / Expo"
const result = await InfluTo.setReferralCode(code, userId);
if (result.grantsAccess) {
  // Unlock premium now
}
```
```swift title="iOS (Swift)"
let result = await InfluTo.setReferralCode(code, appUserId: userId)
if result.grantsAccess == true {
    // Unlock premium now
}
```
```kotlin title="Android (Kotlin)"
val result = InfluTo.setReferralCode(code, appUserId = userId) // suspend
if (result.grantsAccess == true) {
    // Unlock premium now
}
```
```dart title="Flutter (Dart)"
final result = await InfluTo.instance.setReferralCode(code, appUserId: userId);
if (result.grantsAccess == true) {
  // Unlock premium now
}
```
```ts title="Web / Capacitor / PWA"
const result = await InfluTo.setReferralCode(code, userId);
if (result.grantsAccess) {
  // Unlock premium now
}
```
<!-- /tabs -->

`applyCode()` and the ready-made components validate first and then apply, but their result doesn't carry the grant flags. If you use them, call `identifyUser` first (or pass `appUserId`) and, after a successful apply, check whether the result's campaign type is `FREE_ACCESS` — then call `checkAccess()` and unlock. `setReferralCode()` on its own doesn't validate the code first, so validate it yourself or use `applyCode()` for codes people type.

Redeeming the same code again doesn't use another seat; it renews the grant.

## Gate premium on checkAccess()

`checkAccess()` asks InfluTo whether this user currently has free access. It works the same for RevenueCat and store-direct apps. Combine it with your normal store entitlement:

<!-- tabs -->
```tsx title="React Native / Expo"
const { hasAccess } = await InfluTo.checkAccess(userId);
const isPremium = hasStoreEntitlement || hasAccess; // hasStoreEntitlement: your RevenueCat or StoreKit check
```
```swift title="iOS (Swift)"
let access = await InfluTo.checkAccess(appUserId: userId)
let isPremium = hasStoreEntitlement || access.hasAccess
```
```kotlin title="Android (Kotlin)"
val access = InfluTo.checkAccess(appUserId = userId) // suspend
val isPremium = hasStoreEntitlement || access.hasAccess
```
```dart title="Flutter (Dart)"
final access = await InfluTo.instance.checkAccess(appUserId: userId);
final isPremium = hasStoreEntitlement || access.hasAccess;
```
```ts title="Web / Capacitor / PWA"
const { hasAccess } = await InfluTo.checkAccess(userId);
const isPremium = hasStoreEntitlement || hasAccess;
```
<!-- /tabs -->

- If you've called `identifyUser()`, you can leave out the user ID; the SDK uses the stored one.
- A positive answer is cached on the device for 5 minutes; a negative answer is never cached, so a fresh redemption shows up at once.
- On a network error it returns `hasAccess: false`. Don't lock out someone who already has a store entitlement because of it.
- The result also has `expiresAt`, `code` and `source` (`comp`).

## Optional: mirror grants into RevenueCat

If your app checks premium only through RevenueCat, InfluTo can also create each grant in your RevenueCat project as a promotional entitlement. `checkAccess()` works without this; the mirror is for apps that want RevenueCat to see the access too.

Set it up in **Settings → Validation**, on the card **Creator free-access codes (RevenueCat mirror)**:

| Your RevenueCat secret key | Also enter |
|---|---|
| **v2** — with "Customer information → Customers: Read & write" and "Project configuration → Projects: Read" | **Project ID** and **Entitlement ID** |
| **v1** (legacy) | **Entitlement lookup key**, e.g. `pro` |

InfluTo detects the key version when you save. The key is write-only and is never shown again. Then click **Save comp-grant config**.

If the mirror fails for a redemption, the user still gets access through `checkAccess()`. RevenueCat may serve cached customer info right after a grant, so refresh it (for example with RevenueCat's `invalidateCustomerInfoCache()`) if you gate only on RevenueCat.

## Troubleshooting

| Problem | What to check |
|---|---|
| `CODE_NOT_FOUND` | The code is inactive or blocked, or belongs to another of your apps. Codes work only in their own app. |
| `CODE_EXPIRED` | The expiration date has passed, every use is taken, or this person's access window from an earlier redemption is over. Raise **Max Uses** or extend the date in **Edit**. |
| Redemption fails with "Could not identify your account" | Pass the user ID to `setReferralCode()` / `applyCode()`. |
| Premium doesn't unlock | Gate on `checkAccess().hasAccess` as well as your store entitlement. If you rely on RevenueCat only, set up the mirror and refresh RevenueCat's customer info. |
| A creator has no `INFLU-` code | They joined before you enabled auto-issue, or manual code entry is off. |
| Did the RevenueCat mirror work? | Ask an agent to run `influto_list_free_codes` — it reports failed RevenueCat grants per code with the latest error. |

## With an AI agent

`influto_create_free_code` creates a code and `influto_create_free_codes_bulk` up to 500 at once (same rules as the dashboard, including a partner and a group); `influto_list_free_codes` lists codes with their redemptions, the creator each `INFLU-` code belongs to, and RevenueCat mirror problems; `influto_update_app` turns auto-issued creator codes on and sets their duration. See [Agent tools](https://docs.influ.to/agents/tools.md).

## Next

<!-- cards -->
- [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md) — Add the code field that redeems these codes.
- [SDK reference](https://docs.influ.to/reference/sdk.md) — `setReferralCode`, `checkAccess` and every other method.
<!-- /cards -->

---

<!-- https://docs.influ.to/platform/commissions -->
# Commissions and fees

> How InfluTo computes a creator's commission and the 10% platform fee, when commission is earned or reversed, the currency, how rate changes apply, per-creator rates and tiers, and campaign limits.

You pay InfluTo nothing per month. For every purchase a creator brings you, you pay the creator's commission plus InfluTo's 10% platform fee, both calculated on the price of that purchase in US dollars. The amount is reserved from your prepaid [wallet](https://docs.influ.to/platform/wallet.md) when the purchase is verified and paid to the creator in the next monthly payout.

## How a commission is calculated

```text
commission    = price in USD × commission rate     (rounded to the cent)
platform fee  = price in USD × 10%                 (rounded to the cent)
you pay       = commission + platform fee
```

A $9.99 monthly subscription on a campaign paying 30%:

| | Amount |
|---|---|
| Creator commission: $9.99 × 30% = $2.997 | **$3.00** |
| Platform fee: $9.99 × 10% = $0.999 | **$1.00** |
| Reserved from your wallet | **$4.00** |
| Yours (before the store's fee) | $5.99 |

Every renewal repeats the same calculation. Two more examples:

| Purchase | Rate | Commission | Fee | You pay |
|---|---|---|---|---|
| $49.99 yearly subscription | 25% | $12.50 | $5.00 | $17.50 |
| $4.99 weekly subscription | 40% | $2.00 | $0.50 | $2.50 |

The rate is set per campaign as a percentage (see [Create a campaign](https://docs.influ.to/platform/create-campaign.md)).

## The platform fee

- 10% of the purchase price in USD, on each payment that earns a commission: first payments, renewals and one-time purchases.
- No fee on purchases that no creator brought in. Organic sales cost you nothing.
- No fee when the commission is $0 — a 0% campaign used only for tracking, or a creator on a 0% custom rate whom you pay outside InfluTo.
- No monthly or setup fee. The only other money involved is your wallet balance, which stays yours until creators earn it.

## When commission is earned

| What happens | Commission |
|---|---|
| A free trial starts | Nothing yet |
| The trial converts, or the user buys without a trial | Yes |
| Each subscription renewal | Yes, at the rate locked when the user was acquired — unless the campaign pays on **First purchase only**, the user's commission period has ended, or the campaign's budget is used up (see [Limits](#limits-commission-period-conversion-cap-and-budget)) |
| A one-time in-app purchase | Yes, once per purchase |
| A refund or chargeback | The commission for that payment is reversed |
| A sandbox, TestFlight or other test purchase | Never — tests don't touch money or stats |
| A purchase with no creator attached | Nothing, and no fee |

Purchases count only after InfluTo has verified them with the store, through [RevenueCat](https://docs.influ.to/integrations/revenuecat.md) or [store-direct](https://docs.influ.to/integrations/store-direct.md).

### The first creator keeps the user

Once a creator brings in a user — with a trial or a first payment — that user's later purchases and renewals stay with that creator, even if the person types another creator's code later. A code entered after someone's first purchase doesn't change who earns. How users are matched to creators in the first place is on [Attribution](https://docs.influ.to/advanced/attribution.md).

## Refunds and chargebacks

When the store reports a refund or chargeback, InfluTo reverses exactly what that payment credited — at the rate it was credited at, never the current one.

- **Not yet paid out:** the commission is removed from the creator's pending earnings and is never paid.
- **Already paid out:** the commission is deducted from the creator's next payout.

Which refunds are detected automatically:

- **RevenueCat apps:** refunds arrive as RevenueCat `REFUND` events.
- **Store-direct apps:** refunds of subscriptions and one-time purchases are reversed automatically on both stores (InfluTo checks with Apple and Google).

## Currency

Commissions and fees are always calculated in US dollars, whatever currency the user paid in.

- **RevenueCat apps:** InfluTo uses the USD price RevenueCat reports with each event.
- **Store-direct apps:** InfluTo converts the local price to USD at the exchange rate of the purchase date. A renewal three months later uses that later day's rate.

Wallet top-ups and creator payouts are in USD.

## Changing the commission rate

Change the rate on the campaign page in **Campaign Settings → Commission Percentage**, then **Save Settings**.

- **Increases apply immediately.** Creators on the campaign are emailed, and users acquired from then on earn the new rate. Applying them at once means nobody promoting during a notice period gets locked in at the lower rate.
- **Decreases are scheduled with 7 days' notice.** Creators are emailed when you schedule it. The new rate applies at the first hourly tick after the 7 days are up, and the campaign page shows "Scheduled: …% from …" until then.
- **To cancel a scheduled decrease**, click **Cancel change** on the campaign page, or enter the current rate again. Entering a different rate replaces the scheduled one.
- Every change is recorded: who asked for it, the old and new rate, when it was requested and when it applied.
- The same rules apply to changes made through the API and AI agents. There is no way to lower a rate without notice.

### Existing subscribers keep their rate

A subscriber's terms lock when they are acquired — the rate and whether the campaign pays on every payment or the first purchase only. Renewals keep the locked terms, one-time purchases use the rate in force at the time, and refunds reverse exactly what was credited. Nothing is recalculated afterwards, in either direction.

```text
Jan 1   Campaign at 30%
Jan 15  User A subscribes                → locked at 30%
Feb 1   You lower the rate to 25%        → applies Feb 8 after 7 days' notice
Feb 15  User B subscribes                → locked at 25%
March   Both renew                       → A earns 30%, B earns 25%
```

## Per-creator rates

One creator can earn a different rate from the rest of the campaign:

- **When you invite them**, through an AI agent: `influto_invite_creator` or `influto_invite_creators_batch` with `custom_commission_percentage`. See [Invite creators](https://docs.influ.to/platform/invite-influencers.md#invite-with-an-ai-agent).
- **Any time after they joined**: on the campaign page, open the creator and set **Commission rate**, or use **Use campaign rate** to remove their custom rate. Agents use `influto_set_creator_commission`.

A change to one creator's rate follows the same rules as a campaign change: a raise applies immediately, a cut (including going back to a lower campaign rate) waits 7 days' notice and the creator is emailed, and every change is recorded.

- The custom rate replaces the campaign rate for that creator and follows the same lock-at-acquisition rule.
- Changing the campaign rate later doesn't change a creator's custom rate.
- A custom rate of 0 means you pay that creator outside InfluTo, and no platform fee is charged on their sales.

### Rate tiers

A campaign can raise rates automatically as creators perform — for example 30% for everyone, 35% from a creator's 10th paid subscriber and 40% from their 25th. Set up to five tiers in **Edit Campaign → Rate tiers** (agents: `tier_rules` on `influto_update_campaign`). Each tier needs more paid subscribers and a higher rate than the one before.

- When a creator reaches a tier, their rate rises at once. The subscriber who crossed the threshold already earns the new rate.
- Tiers only raise rates: a creator with a higher custom rate keeps it.
- Subscribers acquired earlier keep the rate they were locked at.

## Limits: commission period, conversion cap and budget

Three optional limits in **Edit Campaign** (agents: `commission_duration_months`, `max_conversions` and `max_commission_total` on `influto_create_campaign` / `influto_update_campaign`; `0` removes a limit):

| Limit | What it does |
|---|---|
| **Commission period (months)** | Renewals stop earning this many months after each subscriber's first payment, e.g. 12. The period locks when the subscriber is acquired: changing it only affects subscribers acquired afterwards, and subscribers from before you set it keep earning for as long as they subscribe. |
| **Max paid conversions** | Paid conversions beyond the cap earn nothing (a trial that converts after the cap is tracked without commission). Renewals of earlier subscribers keep earning. |
| **Commission budget ($)** | Total commission the campaign may pay. The payment that crosses the budget earns only what's left; after that nothing in the campaign earns, renewals included. |

When the conversion cap or the budget is reached, the campaign pauses at once (no 72-hour grace period, since new subscribers couldn't earn anything) and the campaign page says why. Raise or remove the limit in **Edit Campaign**, then click **Resume Campaign** — resuming is refused while a limit is still used up. Purchases that a limit stopped from earning still show in your revenue, and cost no platform fee.

## Milestone bonuses

On top of commission, a campaign can pay up to five one-time bonuses for reaching a number of installs, trials or paid subscriptions — for example $40 for a creator's first 10 installs. Approved bonuses are paid from your wallet in the next monthly payout run. Rules and review: [Milestone bonuses](https://docs.influ.to/platform/create-campaign.md#milestone-bonuses).

## Where to see the numbers

- **Campaign page:** revenue and commission per campaign and per creator, plus **Referred Users** with what each referred user has paid and earned their creator.
- **Payouts:** each payout's commission, platform fee and total cost.
- **Billing:** every reservation and payment in the wallet's transaction history and CSV export.

## Next

<!-- cards -->
- [Wallet and payouts](https://docs.influ.to/platform/wallet.md) — Fund the wallet and see when creators get paid.
- [Create a campaign](https://docs.influ.to/platform/create-campaign.md) — Set the rate, the plan price and bonuses.
- [Analytics](https://docs.influ.to/platform/analytics.md) — Revenue and commission over time.
<!-- /cards -->

---

<!-- https://docs.influ.to/platform/wallet -->
# Wallet and payouts

> Fund the prepaid wallet that pays your creators, read available and reserved balance, withdraw unused money, and see when and how creators get paid.

Your wallet is a prepaid creator budget. You top it up, and each time a creator brings you a verified purchase, InfluTo reserves the commission and the 10% platform fee from it. On the 1st of each month the reserved commission is paid out to creators through Stripe. Money you haven't used stays yours and can be withdrawn.

## Add funds

<!-- steps -->

### Open Billing → Add Funds

In the sidebar, click **Billing**. The page is titled **Billing & Wallet**.

### Enter the amount

Enter the **Amount (USD)**. The minimum deposit is $50.

### Pay with Stripe

Click **Continue to Payment** and pay on Stripe's checkout page. The balance updates as soon as Stripe confirms the payment, and the deposit appears on the **Deposits** tab with its receipt.

<!-- /steps -->

Deposits are in US dollars. There is no automatic top-up.

## Available and reserved balance

| Figure | Meaning |
|---|---|
| **Available Balance** | Money you've deposited that isn't committed to creators yet. |
| **Reserved Balance** | Commission and platform fee for verified purchases, held until the next monthly payout. Already taken out of your available balance. |
| **Lifetime Deposited** | Everything you've added. |
| **Lifetime Spent** | Everything that has left the wallet: commissions paid to creators and InfluTo's fee. |

**Wallet Health** at the top of the page estimates how many days your balance lasts at your recent spending rate, and **Usage Predictions** shows the daily burn rate and a 30-day projection.

## What needs a funded wallet

| Action | Requirement |
|---|---|
| Activate a campaign | At least $50 that isn't reserved for pending commissions |
| Send email invitations | The same $50 |
| Invite creators from the marketplace | One open invitation per $20 that isn't reserved |
| Each verified purchase by a referred user | Commission + 10% fee reserved — see [Commissions and fees](https://docs.influ.to/platform/commissions.md) |
| Milestone bonuses | Taken from the wallet at the payout run |

When an action needs more money, the dashboard asks you to add funds; the API answers HTTP 402.

## When the balance runs low

- If your wallet can no longer cover pending commissions, InfluTo pauses your active campaigns. As with a manual pause, purchases by referred users still earn commission for 72 hours, and referral links keep working.
- After you top up, resume each campaign yourself with **Resume Campaign** on its page. Campaigns don't restart on their own.
- There's no low-balance warning email. Watch **Wallet Health** on the Billing page.
- If a verified purchase arrives that the wallet can't cover, the creator's commission is still recorded, and your organization's owners and admins get an email about it (at most one a day). If the money still isn't there at payout time, the payout is retried daily for up to 30 days, so topping up lets it through.

## Withdraw unused funds

Click **Withdraw Funds**, enter an amount and confirm. The money is refunded to the payment method you deposited with — newest deposit first — so no bank connection is needed. Card refunds can take several business days to show up on your statement.

You can withdraw only when:

- no campaign is active (pause them first),
- nothing is reserved for pending commissions (reserved money clears at the monthly payout),
- there are no commissions in flight from recent referral clicks,
- no milestone bonuses are waiting for review or payout.

Only money that came in through Stripe can be refunded this way. For anything else, email [hello@influ.to](mailto:hello@influ.to).

## Automatic refund of an unused wallet

If you fund the wallet and never use it — nothing spent, nothing reserved and no active campaign — InfluTo emails you a reminder 23 days after your most recent deposit and refunds every deposit to its original payment method on day 30. Once any money has been spent or a campaign is active, this no longer applies; withdraw manually instead.

## Receipts and exports

- **Deposits** tab — every deposit with a **Receipt** link to Stripe's receipt.
- **Billing details** — your company or legal name, VAT or tax ID and address, used on your billing documents.
- **Export CSV** — the last 12 months of wallet transactions: date (UTC), type, description, amount, balance after and currency.

## How creators get paid

| | |
|---|---|
| **When** | On the 1st of each month at 01:00 UTC, InfluTo creates payouts for the previous calendar month. |
| **Minimum** | $20. Smaller balances roll over to the next month. |
| **How** | Stripe Connect transfers in USD. Creators complete Stripe's identity checks once. |
| **Where** | Creators in 33 countries: the United States, Canada, the United Kingdom, Switzerland, Norway, Liechtenstein and the 27 EU countries. |
| **What's included** | Commission for the month, approved milestone bonuses, minus clawbacks for refunds of commissions already paid. |

- A creator who hasn't finished Stripe onboarding isn't paid yet; their earnings carry over to a later run.
- Failed transfers are retried automatically: when your wallet is short, once a day for up to 30 days; for temporary Stripe errors, with increasing gaps.
- The **Payouts** page lists every payout with the creator, period, conversions, commission, platform fee and total cost, plus **Failed** and **Processing** tabs.

## For AI agents

Agents can see the wallet but never move money. `influto_get_wallet` returns the balance, the reserved amount, `safe_available` (available minus reserved), whether you can activate campaigns, and your remaining invitation capacity. When an activation or invitation returns 402, `influto_get_wallet_topup_link` gives you a link to the Billing page, where you finish the payment yourself while signed in. See [Agent tools](https://docs.influ.to/agents/tools.md).

## Next

<!-- cards -->
- [Commissions and fees](https://docs.influ.to/platform/commissions.md) — What each purchase costs and how refunds are handled.
- [Create a campaign](https://docs.influ.to/platform/create-campaign.md) — Activate a campaign once the wallet is funded.
<!-- /cards -->

---

<!-- https://docs.influ.to/platform/analytics -->
# Read your program's analytics

> What InfluTo counts — clicks, attributed installs, trials, paid conversions, revenue and commission — where each number lives, how to read the funnel, and how to see results per group or post.

InfluTo measures one thing end to end: which creators bring you installs and paying users, and what they earned. Every number uses the same definitions on every screen and in the agent API, and only production data counts — sandbox and test purchases never show up in your stats.

## What InfluTo counts

| Metric | Definition |
|---|---|
| **Clicks** | Taps on creators' referral links, after cleaning: repeat taps from the same person count once, and suspicious clicks and link-preview bots are left out. |
| **Installs** | Installs attributed to a creator: a click matched to the install by link-click matching, or a code typed into your app. Flagged clicks and sandbox activity don't count. |
| **Trials** | Referred users who started a free trial. |
| **Paid conversions** ("Paid Subs") | Referred users who became paying customers — directly or when their trial converted. |
| **Active subscribers** | Referred users who are paying right now. |
| **Revenue** | What referred users paid, in USD, across first payments, renewals and one-time purchases. |
| **Commission** | What creators earned on that revenue. |

Organic installs and purchases — the ones no creator brought in — don't count toward any creator. You can still see organic purchases next to attributed ones in the dashboard's **Revenue Overview** and filter organic events in **Real-Time Events**.

A code typed into your app counts as a click and an install for that creator, because the person is already in your app when they enter it.

### Raw, flagged and clean clicks

The headline click number is always the cleaned one. To see what was removed, InfluTo also keeps:

- **raw** — every tap that was recorded,
- **flagged** — taps marked as suspicious,
- **canonical** — the cleaned number shown everywhere.

The campaign page shows this under **Total Clicks** as "Includes … raw hits · … flagged as suspicious". Agents get it as `clicks.decomposition` (`raw`, `flagged`, `canonical`).

### Why a click gets flagged

InfluTo screens every tap for automated and abusive traffic — bots, link-preview fetchers, scripted or repeated tapping — before it counts. Flagged clicks stay on record but are excluded from click and install counts and from [milestone bonus](https://docs.influ.to/platform/create-campaign.md#milestone-bonuses) progress, so a creator can't inflate their numbers. The exact rules aren't published, so they can't be gamed.

## Where to find each number

| Screen | What it shows |
|---|---|
| **Dashboard** | Installs from creators, active campaigns, creators, and **Revenue Overview** for the last 30 days, split attributed and organic. |
| **Analytics** | **Last 7 / 30 / 90 days**: **Revenue Trend**, the **Conversion Funnel** (Clicks → Installs → Trials → Paid Subs) with the overall conversion rate, **By group / tag** (the funnel per tagged link — see [Results per group or post](#results-per-group-or-post)) and **Top Performing Affiliates**. |
| **Campaigns → a campaign** | Total Clicks, Installs, Trials Started, Paid Subs, Revenue and Commission; the **Campaign Affiliates** table per creator; **Referred Users** with payments, total paid and commission for each referred user. |
| **Affiliates** | Every creator across campaigns. Open one for clicks, conversions, conversion rate, revenue, commission earned, pending commission and active subscribers. |
| **Real-Time Events** | The latest 100 SDK events and purchase webhooks, refreshed every 5 seconds. Filter by **Attribution** (Attributed / Organic), **Environment** (Production / Sandbox) and **Type**. It also shows sandbox activity, so it's the place to watch while you test. |
| **Payouts** | What each creator was paid, with commission, platform fee and total cost. |

## How to read the funnel

```text
Clicks  →  Installs  →  Trials  →  Paid
        install rate  trial rate   trial-to-paid
```

Look for the step where most people drop out:

- **Lots of clicks, few installs.** People tap but don't install. Check the store listing they land on, and whether the creator's audience matches your app. Remember that link-click matching only connects installs to taps from the last 72 hours (see [Attribution](https://docs.influ.to/advanced/attribution.md)), and that people who install later from a store search show up as organic. A code field in your app catches more of them — see [Referral codes](https://docs.influ.to/guides/referral-codes.md).
- **Installs, but few trials or purchases.** Onboarding or the paywall is losing people. Consider a better offer for referred users — see [Referral offers](https://docs.influ.to/guides/referral-offers.md).
- **Trials, but few become paid.** Look at pricing and what the trial shows. Commission is only earned once a trial converts.

The steps aren't strictly nested: a user who buys without a trial counts as paid but not as a trial, so **Paid** can be higher than **Trials**.

## Results per group or post

One creator code is often posted in many places — several Facebook groups, a TikTok bio, a newsletter. Tag the link once per place and InfluTo shows clicks, installs, trials and paid subscriptions for each place separately.

### Tag the links

Add a tag to the creator's referral link. Use a short name per place; the code stays the same:

```text
https://influ.to/{app_slug}/{CODE}?s=fb-hu-keto
https://influ.to/{app_slug}/{CODE}?s=fb-hu-vegan
https://influ.to/{app_slug}/{CODE}?s=tiktok-bio
```

| Parameter | Shown as | Notes |
|---|---|---|
| — | **Code** | The code itself (a creator's code or one of your [tracking codes](https://docs.influ.to/platform/create-campaign.md#tracking-campaigns)). No tag needed; codes typed into the app count under their code. |
| — | **Code → post (?s=)** | Per code, then per `?s=` value. |
| `s` (or `sub1`, `sub`, `subid`) | **Group (?s=)** | The simplest choice: one value per group or post. |
| `s2` (or `sub2`) | **Second tag (?s2=)** | A second level if you need one, for example the post inside a group. |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | **UTM source**, **UTM medium**, … | Standard UTM tags, if your links already use them. |
| — | **Referring site** | The site the tap came from, when the browser reports it (`www.` dropped; `m.facebook.com` and `facebook.com` stay separate). No tag needed. |

Tags are saved with each tap, so they work whether the person installs from the App Store or Google Play. They don't change who gets credited or what anyone earns. Values are kept as written (up to 255 characters): `FB-hu-keto` and `fb-hu-keto` are two different rows, so agree on one spelling with your creators. Taps from before a link was tagged stay untagged.

### Read the breakdown

Open **Analytics → By group / tag**, choose what to group by, the period and, if you have several campaigns, one campaign. Each row shows clicks, installs, trials, paid, **Revenue** (what those subscribers have paid so far, in USD, refunds deducted) and the **Click → install** and **Click → paid** rates. Below the tagged rows:

- **Untagged** — taps without the chosen tag. A code typed into your app has no link and no tag, so it is counted here.
- **Total** — every tap on your creators' links in the period (in the chosen campaign, if you picked one).

How the numbers are counted:

- **By tap date.** A row counts the taps made in the period and everything they led to, even if the install or purchase came later. The **Conversion Funnel** above counts trials and purchases by the date they happened, so the two don't always match.
- **Clicks are cleaned the same way as everywhere else**, per row: someone who opens two differently tagged links within 5 minutes counts once in each row. That's why the rows can add up to more than **Total**, which is the same click number as the rest of the dashboard.
- **Trials and paid count under a tag only when the purchase is tied to that person's own tap.** A purchase credited to the creator that can't be tied to one person's tap isn't credited to any tag: it is listed as "not tied to a tag" under the table and included in **Total**. A purchase with no tap on the link at all — for example a code your app set through RevenueCat — isn't in this breakdown, so trials and paid here can be lower than in the Conversion Funnel.

The dashboard lists the 100 busiest values; agents can ask for up to 500.

### Agents and the API

`influto_get_funnel_breakdown` returns the same table: pass `appId` and `groupBy` (`code`, `sub1`, `sub2`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` or `referrer_host`, or up to three of them separated by commas, such as `code,sub1` — rows then also carry `values` per dimension), optionally `days` (1–3650, default 30), `campaignId`, `referralCode` and `limit`. Over REST it is `GET /api/agent/apps/{app_id}/analytics/breakdown?group_by=sub1&days=30` with an agent key or OAuth token (scope `analytics:read`). The response has `rows`, `untagged`, `unmatched` (the purchases not tied to a tag), `totals` and `notes` that restate the counting rules above. Every row, `unmatched` and `totals` include `revenue`.

## With an AI agent

| Question | Tool |
|---|---|
| How is the app doing? Clicks with breakdown, installs, trials, paid conversions, active subscribers, revenue, commission and rates for `7d`, `30d`, `90d` or `all` | `influto_get_analytics_overview` |
| Where does a campaign lose people? Funnel counts with step rates | `influto_get_campaign_funnel` |
| Which group, post or UTM campaign brought the installs and sales? The funnel per link tag | `influto_get_funnel_breakdown` |
| Who are the best creators? Ranked by revenue for a period | `influto_list_top_affiliates` |
| Everything about each creator in a campaign, including milestone progress | `influto_list_affiliates` |
| Did a post cause a spike? Day-by-day series for 1–365 days | `influto_get_daily_performance` |
| Did my test purchase arrive? Latest events, filterable by environment | `influto_recent_events` |

In the overview, `conversions.total` means paid conversions; `conversions.acquired_users` counts every referred user, including trials that never paid. See [Agent tools](https://docs.influ.to/agents/tools.md).

## Next

<!-- cards -->
- [Commissions and fees](https://docs.influ.to/platform/commissions.md) — How revenue turns into commission.
- [Verify the integration](https://docs.influ.to/integrations/testing.md) — Use Real-Time Events and test purchases to check everything works.
<!-- /cards -->

---

<!-- https://docs.influ.to/guides/referral-codes -->
# Let users enter a referral code

> Add a code field so people who hear a creator's code — in a podcast, a video or from a friend — are credited to that creator, plus prefill, errors and testing.

Links only work when someone taps them. When a creator says "use code MAYA" in a podcast, a video or a conversation, the listener installs from the store and has nothing to tap. A code field in your app closes that gap: the person types the code, and the creator is credited exactly — no matching involved, and no attribution window.

The same field also redeems free-access codes, so one field covers referrals, creator access and your own comp codes.

## When a code field matters

- Creators who talk about your app rather than link to it: podcasts, YouTube and TikTok videos, livestreams, word of mouth.
- Platforms where links aren't clickable, or audiences who search the store instead of tapping.
- Creators who need to try your premium features first — their `INFLU-` access code goes in the same field ([Creator access codes](https://docs.influ.to/platform/creator-access-codes.md)).

A code must be entered before the user's first purchase. After that, the user stays with whoever acquired them, or stays organic — see [Commissions and fees](https://docs.influ.to/platform/commissions.md#the-first-creator-keeps-the-user).

## Turn on manual code entry

Open **Settings → Advanced**, check **My app has the ReferralCodeInput UI component** and click **Save Changes**. The label names the ready-made component, but your own field counts too.

This setting tells creators they can share their code by voice — their dashboard then suggests "say your code" content — and it's required before you can turn on creator access codes. It doesn't change how codes are checked, so turn it on once the app version with the field is live.

## Where to put the field

- **Onboarding**, as a "Have a code?" step before the paywall. This catches most people, because the code is still fresh in their mind.
- **On the paywall**, as a small "Have a referral code?" link. Last chance before the first purchase.
- **In settings**, for creators redeeming an access code and people who skipped onboarding.

Keep it optional, with a skip button. Prefill it when InfluTo already knows the code (below), so the user only has to confirm.

## Use the ready-made component, or your own field

Each SDK ships a code field that checks the code with InfluTo, applies it and shows a valid or invalid state. Or call the SDK yourself: `applyCode()` checks the code with InfluTo and, if it's valid, applies it in one step. These are the same snippets the dashboard shows on **Setup & SDK**:

<!-- tabs -->

```tsx title="React Native / Expo"
// Validate, then apply a code the user typed
const result = await InfluTo.applyCode('FITGURU30');
if (result.valid && result.applied) {
  // Unlock the offer
}

// Or drop in the ready-made UI:
import { ReferralCodeInput } from '@influto/react-native-sdk/ui';
<ReferralCodeInput onApplied={(result) => {/* ... */}} />

// Free-access codes (INFLU-… or your comp codes): redeem with
// setReferralCode(code) after identifyUser (or pass appUserId) — grantsAccess
// === true means unlock premium now — and gate premium on (await InfluTo.checkAccess()).hasAccess.
```

```swift title="iOS (Swift)"
// Validate + apply a code the user typed
let result = await InfluTo.applyCode("FITGURU30")
if result.valid && result.applied == true {
  // Unlock the offer
}

// Or drop in the SwiftUI field: InfluToReferralCodeInput(onApplied: { result in … })
// Free-access codes (after identifyUser): setReferralCode(code).grantsAccess == true
// → unlock premium, and gate premium on (await InfluTo.checkAccess()).hasAccess.
```

```kotlin title="Android (Kotlin)"
// Validate + apply a code the user typed
val result = InfluTo.applyCode("FITGURU30")   // suspend
if (result.valid && result.applied == true) {
  // Unlock the offer
}

// Or the Compose field (android-sdk-ui): InfluToReferralCodeInput(onApplied = { result -> … })
// Free-access codes (after identifyUser): setReferralCode(code).grantsAccess == true
// → unlock premium, and gate premium on InfluTo.checkAccess().hasAccess.
```

```dart title="Flutter (Dart)"
// Validate + apply a code the user typed
final result = await InfluTo.instance.applyCode('FITGURU30');
if (result.valid && result.applied == true) {
  // Unlock the offer
}

// Or the ready-made widget: ReferralCodeInput(onApplied: (result) { … })
// Free-access codes (after identifyUser): (await setReferralCode(code)).grantsAccess
// == true → unlock premium, and gate premium on (await checkAccess()).hasAccess.
```

```ts title="Web / Capacitor / PWA"
// Validate, then apply a code the user typed
const result = await InfluTo.applyCode('FITGURU30');
if (result.valid && result.applied) {
  // Unlock the offer
}

// React / Ionic React: drop in the ready-made field
import { ReferralCodeInput } from '@influto/web/react';
<ReferralCodeInput onCodeApplied={(code) => {/* ... */}} />

// Free-access codes: (await InfluTo.setReferralCode(code)).grantsAccess → unlock
// premium, and gate premium on (await InfluTo.checkAccess()).hasAccess.
```

<!-- /tabs -->

| SDK | Component | Import / package |
|---|---|---|
| React Native / Expo | `ReferralCodeInput` | `@influto/react-native-sdk/ui` |
| iOS (Swift) | `InfluToReferralCodeInput` (SwiftUI) | module `InfluTo` |
| Android (Kotlin) | `InfluToReferralCodeInput` (Compose) | `to.influ:android-sdk-ui` |
| Flutter (Dart) | `ReferralCodeInput` | `package:influto/influto.dart` |
| Web / Capacitor / PWA | `ReferralCodeInput` (React) | `@influto/web/react` |

All components prefill the code by default and bind it to the user from `identifyUser` (or an `appUserId` you pass). InfluTo then knows which account the code belongs to, which helps match purchases and is required for free-access codes. Props, labels and styling: [UI components](https://docs.influ.to/reference/ui.md).

## Prefill the code

If the user arrived through a creator's link and InfluTo matched the install, `getPrefilledCode()` returns that creator's code (otherwise `null`). The components do this for you; in your own field:

<!-- tabs -->
```tsx title="React Native / Expo"
const code = await InfluTo.getPrefilledCode(); // string | null
```
```swift title="iOS (Swift)"
let code = await InfluTo.getPrefilledCode() // String?
```
```kotlin title="Android (Kotlin)"
val code = InfluTo.getPrefilledCode() // String? — not a suspend function
```
```dart title="Flutter (Dart)"
final code = await InfluTo.instance.getPrefilledCode(); // String?
```
```ts title="Web / Capacitor / PWA"
const code = await InfluTo.getPrefilledCode(); // string | null
```
<!-- /tabs -->

## Handle invalid codes

Input is forgiving: codes are trimmed and uppercased, spaces and invisible characters from copy-paste are removed, and InfluTo also tries common look-alikes (`I` and `L` for `1`, `O` for `0`). When a code still doesn't work, the validation result has `valid: false` and an error code:

| Error code | Meaning | Suggested message |
|---|---|---|
| `INVALID_FORMAT` | Not 4–20 characters after cleaning | "Codes are 4–20 letters and numbers." |
| `CODE_NOT_FOUND` | No such code in this app — or its campaign is paused or the creator is no longer active | "We couldn't find that code." |
| `CODE_EXPIRED` | A free-access code past its expiry date or out of uses | "This code has expired." |
| `NETWORK_ERROR` | The SDK couldn't reach InfluTo, or isn't initialized | "Couldn't check the code. Try again." |

The field is `error_code` in React Native and web, and `errorCode` in iOS, Android and Flutter (an enum on Android). Let users try again or skip; never block onboarding on a failed code.

## Keep creators' names private by default

When a code is valid, the response includes the campaign and, for creator codes, the creator's name. The components show neither unless you opt in with `showCampaignName` or `showReferrerName`. Show a creator's name only if they've agreed to it — a generic "Code applied" is enough for most apps.

## Free-access codes in the same field

`INFLU-` creator codes and your own comp codes from **Free Access Codes** go in the same field. They don't earn commission; they unlock premium. When one is applied, the validation result's campaign type is `FREE_ACCESS`, and `setReferralCode()` returns `grantsAccess: true`. Gate premium on `checkAccess().hasAccess` as well as your store entitlement. Details: [Creator access codes](https://docs.influ.to/platform/creator-access-codes.md).

## Test a code

- Referral codes validate only while their campaign is **Active** and the creator is active, so you need an activated campaign with at least one creator. You can't join your own organization's campaigns, so invite a colleague or a second email address you control. See [Invite creators](https://docs.influ.to/platform/invite-influencers.md).
- To test the field itself without a creator, create a free-access code on **Free Access Codes**. It doesn't need a campaign.
- Watch **Real-Time Events** while you apply the code. Applying a creator's code counts as a click and an install for that creator in your stats, so test with a test creator, not a real one.
- Then make a sandbox purchase and check it arrives attributed: [Verify the integration](https://docs.influ.to/integrations/testing.md).

## Next

<!-- cards -->
- [Give referred users a better offer](https://docs.influ.to/guides/referral-offers.md) — Show a different paywall to people who entered a code.
- [UI components](https://docs.influ.to/reference/ui.md) — Every prop of the ready-made code field.
- [SDK reference](https://docs.influ.to/reference/sdk.md) — `validateCode`, `applyCode`, `setReferralCode` and `getPrefilledCode` on every platform.
<!-- /cards -->

---

<!-- https://docs.influ.to/guides/referral-offers -->
# Give referred users a better offer

> Show people who came through a creator a different paywall, a longer trial or a discount — gated in your app or with RevenueCat Targeting.

Creators sell your app more easily when their audience gets something for using their link or code: a longer free trial, a first-month discount, a better yearly price. InfluTo tells your app whether the user was referred; what you offer them is up to you and is set up in your own paywall, in RevenueCat, or in the stores.

There are two ways to decide who sees the offer: check `checkAttribution()` in your app, which works with any purchase path, or let RevenueCat Targeting pick the offering from a subscriber attribute the SDK sets.

## Know whether the user was referred

`checkAttribution()` returns `attributed: true` when InfluTo connected the install to a creator — through link-click matching, a link that carried the code into the app, or a code the user typed into your app. The result is stored on the device, so later calls are instant. Call it before you show the paywall, and again after your code field if the user entered a code there.

<!-- tabs -->
```tsx title="React Native / Expo"
const attribution = await InfluTo.checkAttribution();
const paywall = attribution.attributed ? 'referral' : 'standard';
```
```swift title="iOS (Swift)"
let attribution = await InfluTo.checkAttribution()
let paywall = attribution.attributed ? "referral" : "standard"
```
```kotlin title="Android (Kotlin)"
val attribution = InfluTo.checkAttribution() // suspend
val paywall = if (attribution.attributed) "referral" else "standard"
```
```dart title="Flutter (Dart)"
final attribution = await InfluTo.instance.checkAttribution();
final paywall = attribution.attributed ? 'referral' : 'standard';
```
```ts title="Web / Capacitor / PWA"
const attribution = await InfluTo.checkAttribution();
const paywall = attribution.attributed ? 'referral' : 'standard';
```
<!-- /tabs -->

`attribution.referralCode` tells you which creator, if you want a creator-specific deal.

> [!NOTE]
> A free-access code typed into the code field also marks the user as referred — on the device, and in RevenueCat's `influto_referral` when the SDK writes RevenueCat attributes. Those users usually have premium already and skip the paywall; if not, check the code type when it's applied (see [Creator access codes](https://docs.influ.to/platform/creator-access-codes.md)).

## Option 1: Gate the offer in your app

This works with RevenueCat and store-direct alike. Create the better offer as its own product (or offering) in your store setup — for example a yearly plan with a 14-day trial instead of 7 — and show it when `attributed` is true. Purchases of that product are verified and credited to the creator like any other.

## Option 2: RevenueCat Targeting on `influto_referral`

When the SDK attributes a user, it also writes two RevenueCat subscriber attributes: `influto_code` (the creator's code) and `influto_referral` (the string `"true"`). InfluTo itself only reads `influto_code`; `influto_referral` exists so you can target referred users in RevenueCat.

<!-- steps -->

### Make sure the SDK writes the attributes

React Native does it automatically when `react-native-purchases` is installed, and Android finds the RevenueCat SDK automatically (or takes an explicit setter). iOS needs `revenueCatAttributeSetter`, Flutter `revenueCatHook`, and web a `revenueCat` binding. See the RevenueCat section of your SDK page: [React Native](https://docs.influ.to/sdk/react-native.md#revenuecat) · [iOS](https://docs.influ.to/sdk/ios.md#revenuecat) · [Android](https://docs.influ.to/sdk/android.md#revenuecat) · [Flutter](https://docs.influ.to/sdk/flutter.md#revenuecat) · [Web](https://docs.influ.to/sdk/web.md#revenuecat).

### Create the referral offering in RevenueCat

Add an offering with the better packages — for example products with a longer trial or an introductory price.

### Add a Targeting rule

In RevenueCat's **Targeting**, create a rule with a **Custom attributes** condition: `influto_referral` is `true`. Serve the referral offering, and place the rule above the one that serves everyone else. RevenueCat compares attribute values as strings, which matches the `"true"` the SDK writes. To give one creator's audience their own deal, target `influto_code` instead, with that creator's code as the value.

### Sync attributes before fetching offerings

RevenueCat normally sends attributes to its servers when the app starts, goes to the background, or makes a purchase. Right after attribution, call RevenueCat's `syncAttributesAndOfferingsIfNeeded()` and show the offering it returns (`current`), so the rule applies in the same session. RevenueCat limits this call to five per minute.

<!-- /steps -->

Your paywall must display RevenueCat's current offering, not a hard-coded one, for Targeting to have any effect. RevenueCat's own documentation is the reference for Targeting and for which conditions its Experiments support: [Targeting](https://www.revenuecat.com/docs/tools/targeting) · [Customer attributes](https://www.revenuecat.com/docs/customers/customer-attributes).

## Store-direct apps

Without RevenueCat, use Option 1: check `checkAttribution()` and show your referral paywall with the better product. Both stores also have their own discount tools — for example App Store offer codes and promotional offers, and Google Play subscription offers with developer-determined eligibility. Each has its own eligibility rules, so check Apple's and Google's documentation before relying on one. InfluTo captures and verifies these purchases the same way as any other — see [Store-direct](https://docs.influ.to/integrations/store-direct.md).

## What a discount does to the commission

Commission is a percentage of what the user actually pays, in USD. A 50% first-month discount halves the creator's commission on that payment, and a longer trial delays the first commission until the trial converts. Renewals at the full price earn the full rate. If you want creators to keep their full first commission, a longer trial is usually the friendlier choice. See [Commissions and fees](https://docs.influ.to/platform/commissions.md).

## Keep it within store rules

- Make the offer a better price or a longer trial for your subscription, paid through the store's own billing.
- Don't pay or reward people for installing the app, or for ratings and reviews. Both stores restrict incentivized installs and reviews — check the App Store Review Guidelines and the Google Play Developer Program Policies before launching any promotion.
- Describe the offer accurately on your paywall, and make sure creators describe it the same way.

## Test it

<!-- steps -->

### Attribute a test install

Enter a test creator's code in your code field on a sandbox build, or install through their link. `checkAttribution()` should return `attributed: true`.

### Check the attributes in RevenueCat

Open the sandbox customer in RevenueCat and confirm `influto_code` and `influto_referral` are set.

### Confirm the paywall

After `syncAttributesAndOfferingsIfNeeded()`, the paywall should show the referral offering. Make a sandbox purchase and watch it arrive in **Real-Time Events** — see [Verify the integration](https://docs.influ.to/integrations/testing.md).

<!-- /steps -->

## Next

<!-- cards -->
- [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md) — More referred users means more people who see the offer.
- [RevenueCat setup](https://docs.influ.to/integrations/revenuecat.md) — Connect the webhook that credits these purchases.
<!-- /cards -->

---

<!-- https://docs.influ.to/agents -->
# Connect an AI agent

> Connect Claude Code, Codex, Cursor or any MCP client to InfluTo in one command, then let the agent integrate the SDK, set up campaigns and verify attribution end to end.

InfluTo runs an MCP server at `https://influ.to/mcp`. Connect your coding agent to it and the agent can do the whole integration from your editor: pick the right SDK, write the code, set up purchase validation, create and fund-check campaigns, invite creators — and prove it worked with a real attributed test purchase. You sign in once in the browser; there are no keys to copy.

## Connect

| Client | How to connect |
|---|---|
| Claude Code | `claude mcp add --transport http influto https://influ.to/mcp` |
| Claude (web / desktop) | Settings → Connectors → Add custom connector → https://influ.to/mcp |
| Codex CLI | `codex mcp add influto --url https://influ.to/mcp` |
| VS Code (Copilot agent mode) | `code --add-mcp '{"name":"influto","type":"http","url":"https://influ.to/mcp"}'` |
| Gemini CLI | `gemini mcp add --transport http -s user influto https://influ.to/mcp` |
| ChatGPT (web) | chatgpt.com/plugins → + → Add custom MCP server → URL https://influ.to/mcp, authentication OAuth → Create as a plugin (Business / Enterprise / Edu; Pro is read-only) |
| Cursor / any MCP client | Add `https://influ.to/mcp` as an HTTP (streamable) MCP server — Settings → MCP → Add server → { "influto": { "url": "https://influ.to/mcp" } } |

The first time the agent calls an InfluTo tool, your browser opens an InfluTo consent page. Sign in (or create an account), choose the organization the agent may act on, untick any permission you don't want to give, and approve. The client keeps the connection and refreshes it on its own; access tokens last up to an hour and refresh automatically.

See and revoke connected agents any time on **Connect AI Agent** in the dashboard.

**For CI and headless runs**, create an agent key (`it_mcp_…`) on the same page — it's shown once — and send it as `Authorization: Bearer $INFLUTO_API_KEY` to the same MCP URL. Keys have the same permissions as an OAuth connection and can be revoked.

## What an agent can do — and can't

With the default permissions an agent can:

- read your apps, campaigns, creators, analytics and wallet balance;
- create and update apps and campaigns (including milestone bonuses and translations in 11 languages);
- invite creators — one at a time or in batches of up to 500 — and create free-access codes;
- run integration checks and send sandbox test purchases.

Some things are impossible for any agent, whatever you approve: moving money (top-ups, transfers, payouts), reading or setting raw credentials, deleting data, and admin actions. When an action needs one of those, the agent gets a dashboard link for *you* to open — to top up the wallet, upload store credentials or upload assets. Secrets and money never pass through the agent.

Full list of 62 tools, the permissions (scopes) and the REST endpoints behind them: [MCP tools and scopes](https://docs.influ.to/agents/tools.md).

## The verify loop

This is what makes an agent's integration trustworthy: it doesn't stop at "the code compiles".

1. The SDK in your build calls `initialize` and records an install.
2. `influto_integration_status` returns an eight-step checklist, from `app_created` to `attributed_conversion`, plus the next actions.
3. `influto_test_integration` sends a sandbox purchase through the real attribution pipeline.
4. `influto_recent_events` shows the purchase arriving with `attributed: true` and the referral code.
5. When `attributed_conversion_count` is at least 1, the integration is proven.

The same checks over plain HTTP: [Verify the integration](https://docs.influ.to/integrations/testing.md).

## Prompts to start with

The server ships five ready-made prompts your client can list:

| Prompt | What it does |
|---|---|
| `launch_campaign` | Create, fund and activate a campaign for an app |
| `recruit_creators` | Plan and send invitations for a live campaign within your limits |
| `weekly_program_report` | A short read of how the program did over the last week |
| `diagnose_attribution` | Find out why installs or purchases aren't credited to creators |
| `fund_and_activate` | Get a draft campaign funded and live |

Or ask in your own words, for example: *"Add InfluTo to this app with store-direct validation and prove a sandbox purchase is attributed."*

## Install as a plugin (Claude Code)

The InfluTo plugin bundles the MCP server with two skills — `influto-integration` writes the SDK code (and works offline), `influto-platform` drives the dashboard tasks:

```bash
/plugin marketplace add influto/influto-plugin
/plugin install influto
```

Source: [github.com/influto/influto-plugin](https://github.com/influto/influto-plugin).

## When something goes wrong

- **Start with `influto_doctor`.** It needs no permissions and reports how the agent is connected, which permissions it has, its organizations and how fresh each app's SDK data is.
- **401** — the connection or key expired or was revoked. Reconnect, or create a new key.
- **403** — a permission is missing; the error names it.
- **404 on an ID you know exists** — it belongs to another organization than the one you approved.
- **402** — the wallet is too low to activate a campaign or invite creators. The agent can give you a top-up link (`influto_get_wallet_topup_link`).
- **429** — more than 240 tool calls in a minute. Slow down and retry.

## For AI assistants reading this

A plain-text version of the agent reference is at [llms-agents.txt](https://docs.influ.to/llms-agents.txt), the docs index at [llms.txt](https://docs.influ.to/llms.txt), and a drop-in `AGENTS.md` for repositories at [docs.influ.to/AGENTS.md](https://docs.influ.to/AGENTS.md).

---

<!-- https://docs.influ.to/agents/tools -->
# MCP tools, scopes and REST API

> Every InfluTo MCP tool, the permission scopes an agent can be granted, and the /api/agent REST endpoints behind them — with auth, limits and error codes.

This is the reference for agents connected to `https://influ.to/mcp`. The tools that read or change your account call the agent REST API under `/api/agent`, so you can use either — same authentication, same permissions, same organization boundaries. The discovery and scaffold tools answer from the SDK registry without touching your account.

The MCP resource `influto://tools` always lists the live set of tools, generated by the server. Two more resources carry reference material: `influto://contract` (the SDK wire contract) and `influto://sdk/{platform}` (each SDK's reference).

## Authentication

- **OAuth 2.1** (what MCP clients use): discovery, dynamic client registration and a PKCE browser consent where you choose the organization and permissions. Access tokens last up to an hour and refresh automatically.
- **Agent keys** `it_mcp_…`: created on **Connect AI Agent** in the dashboard, shown once, revocable. Send `Authorization: Bearer <key>`.

The app's SDK key (`it_…`) doesn't work here, and the dashboard's own API (`/api/apps/…` without `/agent/`) only accepts a signed-in browser session — an agent calling it gets `401` by design.

## Scopes

| Scope | Grants |
|---|---|
| `apps:read` | List and inspect your apps and their integration status |
| `apps:write` | Create and update apps (names, links, creator-code settings) |
| `campaigns:read` | View campaigns, milestones and settings |
| `campaigns:write` | Create and update campaigns, bonuses, and their status |
| `analytics:read` | Read clicks, installs, trials, conversions and revenue analytics |
| `creators:read` | List creators, invitations and access codes |
| `creators:write` | Invite creators and create free-access codes |
| `assets:read` | List marketing assets and content examples |
| `assets:write` | Feature/unfeature assets (uploads stay in the dashboard) |
| `billing:read` | See wallet balance and reserved funds (read-only) |
| `integration:verify` | Run integration checks and sandbox test events |

New keys and OAuth connections get all of these by default; you can untick any on the consent page.

Denied to every agent whatever it's granted: moving money (top-ups, transfers), payouts, raw credentials, deleting data, and admin. These go through dashboard links the human opens while signed in.

## Tools (62)

### Discovery (4)

Pure lookups — which SDK, which validation path, which invariant.

- `influto_list_sdks` — The five SDKs (React Native, iOS, Android, Flutter, Web) with package id, registry, repo and current version.
- `influto_recommend_sdk` — Free-text stack ('expo', 'swiftui', 'kotlin', …; platform/hostStack/framework/language/sdkId accepted as aliases) → the ONE SDK + peer deps.
- `influto_recommend_validation` — Pick the ONE validation path: RevenueCat webhook vs store-direct (never both).
- `influto_explain_contract` — Wire-contract invariants per topic: attribution, purchase, comp, dedup, rc-attributes.

### Scaffold (6)

Version-correct code snippets straight from the SDK registry.

- `influto_scaffold_install` — Install command(s) + peer dependencies for an SDK.
- `influto_scaffold_init` — The one-time initialize() snippet (THROWS on failure — surface it).
- `influto_scaffold_attribution` — The checkAttribution() launch snippet.
- `influto_scaffold_manual_code` — Optional manual referral-code entry / ReferralCodeInput snippet.
- `influto_scaffold_report_purchase` — Store-direct purchase-reporting snippet (skip on the RevenueCat path).
- `influto_scaffold_full` — One call → the exact ordered integration steps for a stack + validation path.

### Provision (7)

Stand up the account side: org → app (+ API key) → campaign.

- `influto_whoami` — The developer + organizations behind the connected agent.
- `influto_create_org` — Create an organization (only when whoami shows none).
- `influto_search_store` — Search the App Store + Google Play for an app's store identifiers.
- `influto_scrape_store` — Scrape store metadata incl. the numeric Apple app_store_id.
- `influto_check_slug` — Is an app slug free? (Slugs are globally unique — first segment of referral URLs.)
- `influto_provision` — Org → app (+ API key + webhook secret) → campaign → activate, in one idempotent call.
- `influto_regenerate_webhook_secret` — Rotate the RevenueCat webhook secret (returned once).

### Configure (7)

Wire the purchase-validation path; secrets go through a dashboard link the human opens.

- `influto_get_validation_status` — Per-platform validation config + what's missing (non-secret).
- `influto_setup_revenuecat` — Auto-wires the RevenueCat webhook inside the developer's RC project (autowire=true by default, using the stored v2 secret key); falls back to exact dashboard_steps.
- `influto_get_credential_upload_link` — Dashboard link the HUMAN opens (signed in) to upload credentials — secrets never transit the agent.
- `influto_set_apple_meta` — Non-secret Apple identifiers: Issuer ID, Key ID, environment, App Store ID.
- `influto_validate_store_credentials` — Run the live credential green-check (loop while retryable).
- `influto_activate_store_direct` — Flip a platform to store-direct once the green-check passed.
- `influto_recommend_validation_for_platforms` — Which path to wire and what it needs (configure-flow reminder).

### Verify (4)

The differentiator: prove a real ATTRIBUTED conversion happened.

- `influto_integration_status` — THE verify rollup: {live, checklist[], attributed_conversion_count, campaign health, …}.
- `influto_recent_events` — Recent SDK events + purchase webhooks with attribution flags (SANDBOX/PRODUCTION filter).
- `influto_test_integration` — Fire a SANDBOX INITIAL_PURCHASE through the real attribution pipeline.
- `influto_verify_user_conversions` — Did a specific app_user_id's purchases attribute?

### Operate (17)

Run the program: apps, campaigns (milestone bonuses + i18n), awards, analytics.

- `influto_list_apps` — Every app across the developer's orgs, with canonical click totals.
- `influto_get_app` — Full app detail incl. *_i18n maps, support_email and creator-code settings.
- `influto_update_app` — Update whitelisted app settings (name_i18n / description_i18n / tagline_i18n merge and mark those locales fresh; editing name/description marks translations stale; credentials excluded).
- `influto_list_campaigns` — Campaigns by app/status with canonical clicks + milestone counts.
- `influto_get_campaign` — Full campaign: commission, bonus_rules, i18n copy, stats.
- `influto_create_campaign` — Full-featured create incl. milestone bonus_rules + i18n (created as DRAFT).
- `influto_update_campaign` — Update a campaign — same surface as create (editing name/description marks existing translations stale), incl. enforced limits and tier rules.
- `influto_create_tracking_codes` — Add house tracking codes (per channel / group / account / page / QR) to a tracking campaign: attribution only, no commission, no user benefit.
- `influto_set_creator_commission` — Set one creator's rate after they joined (or reset to the campaign rate): raises apply now, cuts after notice.
- `influto_set_campaign_status` — Activate/pause; activation enforces the prepaid wallet minimum (402 → top-up link).
- `influto_list_bonus_awards` — Milestone awards with creator identity + live fraud-aware progress.
- `influto_review_bonus_award` — Approve or void an earned milestone award (pre-payout only).
- `influto_get_analytics_overview` — Per-app period rollup: canonical clicks (+ decomposition), installs, trials, conversions, revenue, commission.
- `influto_get_campaign_funnel` — Clicks → installs → trials → paid with step rates (find the leak).
- `influto_get_funnel_breakdown` — The funnel per link tag (?s= group, utm_*, referring site): which group or post a code's clicks, installs, trials and paid came from.
- `influto_list_top_affiliates` — Top creators by period revenue for an app or campaign.
- `influto_get_daily_performance` — Zero-filled daily series for trend checks and charts.

### Grow (17)

Recruit and reward creators; read-only wallet visibility; the doctor.

- `influto_list_affiliates` — Every creator in a campaign: codes, canonical clicks, earnings, milestone progress, INFLU- code state.
- `influto_invite_creator` — Invite one creator by email (localized invitation + personal message; optional custom commission).
- `influto_invite_creators_batch` — Bulk-invite from a list/CSV — live capacity accounting, per-item results, partial success.
- `influto_withdraw_invitation` — Withdraw a PENDING invite (frees a marketplace capacity slot).
- `influto_get_join_link` — The shareable public join-page URL (?lang=xx, OG card) + readiness warnings.
- `influto_list_invitations` — Invitation states across campaigns (default: still pending).
- `influto_list_free_codes` — Free-access codes incl. platform-issued INFLU- creator codes + redemption state.
- `influto_create_free_code` — Mint a comp/free-access code (ambassadors, press, VIPs) — no purchase needed; optionally credited to a partner.
- `influto_create_free_codes_bulk` — Mint up to 500 unique codes at once (testers, vouchers, one per group), labelled with a cohort.
- `influto_list_assets` — Marketing assets creators use for content (filter by type/category).
- `influto_set_asset_featured` — Curate which assets show as join-page content examples.
- `influto_get_asset_upload_link` — Dashboard link the HUMAN opens (signed in) to upload asset files.
- `influto_get_wallet` — READ-ONLY wallet snapshot: balance, reserved, safe_available, can_activate_campaigns, and invite_capacity (marketplace slots + daily email budget) — read before inviting.
- `influto_get_wallet_topup_link` — Link to the billing page — the HUMAN, signed in, completes the Stripe checkout.
- `influto_localize_campaign` — Localize campaign copy, stale-aware: refreshes only missing/stale locales unless forced (server translator, or hands the copy back for the agent to translate + write back).
- `influto_localize_app` — Localize app name/description/tagline, stale-aware (server translator, or hands the copy back for the agent to translate + write back via influto_update_app).
- `influto_doctor` — Auth mode, principal, scopes, orgs, per-app freshness — call FIRST when anything misbehaves.

## REST endpoints

Base URL `https://influ.to`. Machine-readable spec: [influ.to/api/agent/openapi.json](https://influ.to/api/agent/openapi.json).

**Identity & provision**

```http
GET  /api/agent/whoami
GET  /api/agent/doctor
POST /api/agent/organizations
GET  /api/agent/store/search · GET /api/agent/store/scrape
GET  /api/agent/apps/check-slug/{slug}
POST /api/agent/provision
POST /api/agent/apps/{app_id}/regenerate-webhook-secret
```

**Configure validation**

```http
GET  /api/agent/apps/{app_id}/validation-status
POST /api/agent/apps/{app_id}/credential-setup-link
PATCH /api/agent/apps/{app_id}/apple-meta
POST /api/agent/apps/{app_id}/validate-store-credentials
POST /api/agent/apps/{app_id}/activate-store-direct
```

**Verify (the loop)**

```http
GET  /api/agent/apps/{app_id}/integration-status
GET  /api/agent/apps/{app_id}/events/recent
POST /api/agent/apps/{app_id}/test-integration
GET  /api/agent/apps/{app_id}/verify-user-conversions?app_user_id=…
```

**Operate (apps · campaigns · bonuses · analytics)**

```http
GET  /api/agent/apps · GET/PATCH /api/agent/apps/{app_id}
GET  /api/agent/campaigns · GET/PATCH /api/agent/campaigns/{campaign_id}
POST /api/agent/apps/{app_id}/campaigns
POST /api/agent/campaigns/{campaign_id}/status
PATCH /api/agent/campaigns/{campaign_id}/affiliates/{affiliate_id}/commission
POST /api/agent/campaigns/{campaign_id}/tracking-codes
GET  /api/agent/bonus-awards · POST /api/agent/bonus-awards/{award_id}/review
GET  /api/agent/apps/{app_id}/analytics/overview
GET  /api/agent/campaigns/{campaign_id}/funnel
GET  /api/agent/apps/{app_id}/analytics/breakdown?group_by=sub1|utm_campaign|…
GET  /api/agent/analytics/top-affiliates
GET  /api/agent/campaigns/{campaign_id}/daily-performance
```

**Grow (creators · codes · assets · wallet)**

```http
GET  /api/agent/campaigns/{campaign_id}/affiliates
POST /api/agent/campaigns/{campaign_id}/invite
GET  /api/agent/campaigns/{campaign_id}/join-link
GET  /api/agent/invitations
GET/POST /api/agent/apps/{app_id}/free-codes
POST /api/agent/apps/{app_id}/free-codes/bulk
GET  /api/agent/apps/{app_id}/assets · POST /api/agent/assets/{asset_id}/featured
POST /api/agent/apps/{app_id}/asset-upload-link
GET  /api/agent/wallet · POST /api/agent/wallet/topup-link
POST /api/agent/campaigns/{campaign_id}/localize
POST /api/agent/apps/{app_id}/localize
```

## Limits and errors

| Status | Meaning |
|---|---|
| `401` | Missing, expired or revoked token or key |
| `402` | Wallet balance too low for the action (activate a campaign, invite creators) — get a top-up link with `influto_get_wallet_topup_link` |
| `403` | The token lacks a scope; the error names it |
| `404` | Not found — also returned for IDs in organizations you didn't grant, so nothing leaks about other accounts |
| `429` | More than 240 tool calls per minute for one connection |

More limits across the platform: [Limits and errors](https://docs.influ.to/reference/limits-and-errors.md).

---

<!-- https://docs.influ.to/reference/sdk -->
# SDK reference

> Every public method of the five InfluTo SDKs — exact signatures per platform, result fields, what throws, what fails soft, caching and local storage.

This page lists every public method of the InfluTo SDKs, with the exact signature on each platform. It covers React Native 1.7.0, iOS 1.1.1, Android 1.1.1, Flutter 1.1.1 and web 1.0.1. For setup steps, start with your platform's [install guide](https://docs.influ.to/sdk.md); for the HTTP calls behind each method, see the [HTTP API](https://docs.influ.to/reference/http-api.md).

## At a glance

| Method | What it does | Throws? | Notes |
|---|---|---|---|
| [`initialize`](#initialize) | Connects the SDK with your app's key | Yes | Call once at startup; every other method needs it |
| [`checkAttribution`](#checkattribution) | Decides once per install whether a creator referred it | Only if called before `initialize` succeeded (not on iOS) | Result is stored; network errors return "not attributed" |
| [`identifyUser`](#identifyuser) | Links your user ID to this install | No | Lets purchases without the RevenueCat attribute still attribute |
| [`trackEvent`](#trackevent) | Records a custom funnel event | No | Never creates a conversion or commission |
| [`getActiveCampaigns`](#getactivecampaigns) | Lists the app's active public campaigns | No | `[]` on error |
| [`getReferralCode`](#getreferralcode) | Reads the stored code | No | Local read |
| [`getCodeKind`](#getcodekind) | What the stored code is for (React Native 1.7.0+) | No | Local read |
| [`getPrefilledCode`](#getprefilledcode) | The stored code, only when this install is attributed | No | Local read; use it to prefill a code field |
| [`validateCode`](#validatecode) | Checks a typed code without applying it | No | `NETWORK_ERROR` on failure |
| [`setReferralCode`](#setreferralcode) | Applies a code: stores it, tags RevenueCat, records it | No | Returns the free-access fields |
| [`applyCode`](#applycode) | `validateCode`, then `setReferralCode` if valid | No | Adds `applied`; no free-access fields |
| [`checkAccess`](#checkaccess) | Whether InfluTo grants this user free access | No | Positive result cached for 5 minutes |
| [`reportPurchase`](#reportpurchase) | Sends a store-signed purchase for verification (store-direct) | Yes | `503` means retry |
| [Automatic purchase capture](#automatic-purchase-capture) | Reports store purchases for you on store-direct platforms | Varies | Names differ per platform |
| [`clearAttribution`](#clearattribution) | Forgets the local attribution | No | Local only; for testing |

## Conventions

- **Fail-soft.** Only `initialize` and `reportPurchase` throw on network or server errors. Everything else returns a safe value (`attributed: false`, `[]`, `valid: false`, `success: false`, `hasAccess: false`) and logs the error when `debug` is on.
- **Before `initialize` succeeds**, methods return their fail-soft values without a request. `checkAttribution` and `reportPurchase` throw instead (on iOS, `checkAttribution` returns `attributed: false` with the message `SDK not initialized`). On React Native, `enableAutoPurchaseCapture` and `syncExistingPurchases` also throw.
- **Codes** are trimmed and uppercased by the SDK before they're sent. The server also ignores any character outside `A–Z 0–9 _ -` when it looks a code up, but the SDK stores — and writes to RevenueCat — the code as you passed it, so strip other characters (spaces, invisible characters from copy-paste) in your own input field. See [code rules](https://docs.influ.to/reference/limits-and-errors.md#code-format).
- **Async style.** React Native and web return Promises; iOS methods are `async` statics on `InfluTo`; Flutter uses `InfluTo.instance` and Futures; Android methods are `suspend` functions on `object InfluTo`, and every network method also has an overload whose last parameter is a `(Result<T>) -> Unit` callback, for Java or non-coroutine code.
- **Field names.** React Native and web keep the server's snake_case in validation and purchase results (`campaign_type`, `error_code`, `event_type`); iOS, Android and Flutter use camelCase (`campaignType`, `errorCode`, `eventType`). See [Result types](#result-types).

## initialize

Connects the SDK with your app's key (`POST /sdk/init`). Call it once when the app starts, before anything else.

<!-- tabs -->
```tsx title="React Native / Expo"
// initialize(config: InfluToConfig): Promise<void>
import InfluTo from '@influto/react-native-sdk';

await InfluTo.initialize({ apiKey: 'it_…', debug: __DEV__, appVersion: '1.4.0' });
```
```swift title="iOS (Swift)"
// static func initialize(_ config: InfluToConfig) async throws
import InfluTo

try await InfluTo.initialize(InfluToConfig(apiKey: "it_…", debug: true, appVersion: "1.4.0"))
```
```kotlin title="Android (Kotlin)"
// suspend fun initialize(context: Context, config: InfluToConfig)
// fun initialize(context: Context, config: InfluToConfig, callback: (Result<Unit>) -> Unit)
import to.influ.sdk.InfluTo
import to.influ.sdk.InfluToConfig

lifecycleScope.launch {
    InfluTo.initialize(applicationContext, InfluToConfig(apiKey = "it_…", appVersion = BuildConfig.VERSION_NAME))
}
```
```dart title="Flutter (Dart)"
// Future<void> initialize(InfluToConfig config)
import 'package:influto/influto.dart';

await InfluTo.instance.initialize(const InfluToConfig(apiKey: 'it_…', appVersion: '1.4.0'));
```
```ts title="Web / Capacitor / PWA"
// initialize(config: InfluToConfig): Promise<InitResult>
import InfluTo from '@influto/web';
import { capacitorAdapters } from '@influto/web/capacitor';

const init = await InfluTo.initialize({ apiKey: 'it_…', appVersion: '1.4.0', ...(await capacitorAdapters()) });
```
<!-- /tabs -->

**Configuration**

| Field | Platforms | Default | What it does |
|---|---|---|---|
| `apiKey` | All | required | Your app's SDK key (`it_…`) from **Setup & SDK**. One key covers sandbox and production. |
| `debug` | All | `false` | Logs calls and errors. |
| `appVersion` | All | `"unknown"` | Your app's version, sent with `/sdk/init`. |
| `autoCapture` | All | `true` | Reports store purchases automatically on store-direct platforms. On Flutter it's read by the `influto_iap` observer. See [Automatic purchase capture](#automatic-purchase-capture). |
| `oneTimeProductIds` | React Native, Android, web | none | Your Android one-time and consumable product IDs, so captured purchases are validated as one-time rather than subscriptions. Array on React Native and web, `Set<String>` on Android. |
| `revenueCatAttributeSetter` | iOS, Android | `nil` / `null` | Function the SDK calls with the RevenueCat attributes. Android falls back to finding the RevenueCat SDK by reflection when it's not set. |
| `revenueCatHook` | Flutter | `null` | `Future<void> Function(Map<String, String>)`, same purpose. |
| `revenueCat` | Web | none | A function or an object with `setAttributes`; helpers in `@influto/web/revenuecat`. |
| `httpClient` | Flutter | default client | Injectable `http.Client` (tests, custom transport). |
| `runtime`, `storage`, `device`, `http` | Web | detected | Runtime and storage adapters; `capacitorAdapters()` and `cordovaAdapters()` fill them in. |
| `captureLaunchCode` | Web | `true` | Reads `influto_code` / `influto_click` from the page URL during `initialize`. |
| `cleanUrl` | Web | `true` | Removes the `influto_*` parameters from the address bar after reading them. |
| `purchaseSource` | Web | none | Store purchase source for automatic capture. |
| `apiURL` (iOS), `apiUrl` | iOS, Android, Flutter | `https://influ.to/api` | Base URL override for testing. |

React Native has no RevenueCat option: if `react-native-purchases` is installed, the SDK finds it and sets the attributes itself.

**Behavior**

- Throws on a bad key, a network failure or a server error. Catch it and continue; the SDK stays uninitialized for this launch (see [Conventions](#conventions)) and you can try again on the next one.
- If the response says the platform is store-direct (`store_direct: true`) and `autoCapture` isn't `false`, it starts automatic purchase capture.
- Web only: reads a referral code from the launch URL before the request, so a deep-linked referral survives a failed init, and returns the `/sdk/init` response as `InitResult` (`app_id`, `app_name`, `attribution_window_hours`, `campaigns`, `store_direct`, `initialized`).

## checkAttribution

Decides whether this install came from a creator. The first call sends `POST /sdk/track-install`; the result is stored and every later call returns it without a request.

<!-- tabs -->
```tsx title="React Native / Expo"
// checkAttribution(): Promise<AttributionResult>
const attribution = await InfluTo.checkAttribution();
if (attribution.attributed) console.log(attribution.referralCode);
```
```swift title="iOS (Swift)"
// static func checkAttribution() async -> AttributionResult
let attribution = await InfluTo.checkAttribution()
if attribution.attributed, let code = attribution.referralCode { print(code) }
```
```kotlin title="Android (Kotlin)"
// suspend fun checkAttribution(): AttributionResult
val attribution = InfluTo.checkAttribution()
if (attribution.attributed) Log.d("Referral", attribution.referralCode ?: "")
```
```dart title="Flutter (Dart)"
// Future<AttributionResult> checkAttribution()
final attribution = await InfluTo.instance.checkAttribution();
if (attribution.attributed) debugPrint(attribution.referralCode);
```
```ts title="Web / Capacitor / PWA"
// checkAttribution(): Promise<AttributionResult>
const attribution = await InfluTo.checkAttribution();
if (attribution.attributed) console.log(attribution.referralCode);
```
<!-- /tabs -->

Returns an [AttributionResult](#attributionresult).

- **Decided once per install.** Both outcomes, attributed and organic, are stored under `@influto/attribution`. A failed request returns `{ attributed: false, message: "Error checking attribution" }` and stores nothing, so the next launch asks again.
- **When attributed**, the code is stored under `@influto/influto_code` and the SDK sets the RevenueCat attributes `influto_code` = the code and `influto_referral` = `"true"` (a string). React Native 1.7.0+ also returns `codeKind` (`referral`, `tracking` or `free_access`) and sets `influto_referral` = `"false"` for [tracking codes](https://docs.influ.to/platform/create-campaign.md#tracking-campaigns), which give no referral benefit; other SDKs set `"true"` for every code — check `code_kind` from the server if you use tracking codes there. That happens automatically on React Native (with `react-native-purchases` installed) and Android; iOS, Flutter and web need the setter, hook or binding from [`initialize`](#initialize).
- **`attributionMethod`** is `link_param` (a link carried the code into the app), `ip_device_match` (link-click matching) or `manual_entry` (a code applied with `setReferralCode`). See [attribution](https://docs.influ.to/advanced/attribution.md).
- **Web:** a code captured from the launch URL or the Play Install Referrer is sent along and claimed exactly (`link_param`), and it replaces a stored organic result. Concurrent calls share one request.
- Throws before `initialize` succeeded, except on iOS (see [Conventions](#conventions)).

## identifyUser

Tells InfluTo who the user is — typically the RevenueCat app user ID, or your own user ID (`POST /sdk/identify`).

<!-- tabs -->
```tsx title="React Native / Expo"
// identifyUser(appUserId: string, properties?: Record<string, any>): Promise<void>
await InfluTo.identifyUser(userId, { plan: 'free' });
```
```swift title="iOS (Swift)"
// static func identifyUser(_ appUserId: String, properties: [String: AnyCodable]? = nil) async
await InfluTo.identifyUser(userID, properties: ["plan": AnyCodable("free")])
```
```kotlin title="Android (Kotlin)"
// suspend fun identifyUser(appUserId: String, properties: Map<String, Any?>? = null)
InfluTo.identifyUser(userId, mapOf("plan" to "free"))
```
```dart title="Flutter (Dart)"
// Future<void> identifyUser(String appUserId, {Map<String, dynamic>? properties})
await InfluTo.instance.identifyUser(userId, properties: {'plan': 'free'});
```
```ts title="Web / Capacitor / PWA"
// identifyUser(appUserId: string, properties?: Record<string, any>): Promise<void>
await InfluTo.identifyUser(userId, { plan: 'free' });
```
<!-- /tabs -->

- Stores the ID under `@influto/app_user_id` (before the request, so it's kept even if the request fails). `checkAccess` and `reportPurchase` use it when you don't pass a user ID.
- When the server can match this install's attributed click, it attaches the ID to it (the first identify wins). If a RevenueCat event later arrives without the `influto_code` attribute, InfluTo looks for an attributed click with the purchaser's app user ID — so call it early in the first session, as soon as you know the user.
- Call it once per launch, not on every render: identical calls (same key and user) within 60 seconds are answered from memory, and the endpoint is rate limited to 2 requests per second per IP ([limits](https://docs.influ.to/reference/limits-and-errors.md#rate-limits)).
- Fail-soft; does nothing before `initialize`.

## trackEvent

Records a custom event for the funnel on your dashboard (`POST /sdk/event`).

<!-- tabs -->
```tsx title="React Native / Expo"
// trackEvent(options: TrackEventOptions): Promise<void>
// TrackEventOptions { eventType: string; appUserId: string; properties?: Record<string, any>; referralCode?: string; eventId?: string }
await InfluTo.trackEvent({ eventType: 'paywall_viewed', appUserId: userId, properties: { placement: 'onboarding' } });
```
```swift title="iOS (Swift)"
// static func trackEvent(_ options: TrackEventOptions) async
// TrackEventOptions(eventType:appUserId:properties:referralCode:eventId:)
await InfluTo.trackEvent(TrackEventOptions(eventType: "paywall_viewed", appUserId: userID,
                                           properties: ["placement": AnyCodable("onboarding")]))
```
```kotlin title="Android (Kotlin)"
// suspend fun trackEvent(eventType: String, appUserId: String, properties: Map<String, Any?>? = null,
//                        referralCode: String? = null, eventId: String? = null)
InfluTo.trackEvent(eventType = "paywall_viewed", appUserId = userId, properties = mapOf("placement" to "onboarding"))
```
```dart title="Flutter (Dart)"
// Future<void> trackEvent(TrackEventOptions options)
// TrackEventOptions({required eventType, required appUserId, properties, referralCode, eventId})
await InfluTo.instance.trackEvent(const TrackEventOptions(
    eventType: 'paywall_viewed', appUserId: 'user_123', properties: {'placement': 'onboarding'}));
```
```ts title="Web / Capacitor / PWA"
// trackEvent(options: TrackEventOptions): Promise<void>
await InfluTo.trackEvent({ eventType: 'paywall_viewed', appUserId: userId, properties: { placement: 'onboarding' } });
```
<!-- /tabs -->

- **Never creates a conversion or a commission.** Money comes only from verified purchases (RevenueCat or store-direct).
- **Duplicates are dropped.** Without an `eventId`, the SDK generates one: for `trial_started`, `subscription_purchased` and `subscription_renewed` it's derived from the event type, user and properties, so these count once per user and property set even across launches; other events get a random UUID. Pass your own `eventId` to control this. The server also drops an identical event without an ID sent within 60 seconds.
- Fail-soft; does nothing before `initialize`.

## getActiveCampaigns

Lists the app's active **public** campaigns (`GET /sdk/campaigns`), for showing offers in the app.

<!-- tabs -->
```tsx title="React Native / Expo"
// getActiveCampaigns(): Promise<Campaign[]>
const campaigns = await InfluTo.getActiveCampaigns();
```
```swift title="iOS (Swift)"
// static func getActiveCampaigns() async -> [Campaign]
let campaigns = await InfluTo.getActiveCampaigns()
```
```kotlin title="Android (Kotlin)"
// suspend fun getActiveCampaigns(): List<Campaign>
val campaigns = InfluTo.getActiveCampaigns()
```
```dart title="Flutter (Dart)"
// Future<List<Campaign>> getActiveCampaigns()
final campaigns = await InfluTo.instance.getActiveCampaigns();
```
```ts title="Web / Capacitor / PWA"
// getActiveCampaigns(): Promise<Campaign[]>
const campaigns = await InfluTo.getActiveCampaigns();
```
<!-- /tabs -->

Each [Campaign](#campaign) has `id`, `name`, `description` and the creator commission percentage. Private and invite-only campaigns aren't included. Returns an empty list before `initialize` or on any error.

## getReferralCode

Returns the stored code — from attribution or from a code the user applied — or null. No request.

<!-- tabs -->
```tsx title="React Native / Expo"
// getReferralCode(): Promise<string | null>
const code = await InfluTo.getReferralCode();
```
```swift title="iOS (Swift)"
// static func getReferralCode() async -> String?
let code = await InfluTo.getReferralCode()
```
```kotlin title="Android (Kotlin)"
// fun getReferralCode(): String?   (not suspend)
val code = InfluTo.getReferralCode()
```
```dart title="Flutter (Dart)"
// Future<String?> getReferralCode()
final code = await InfluTo.instance.getReferralCode();
```
```ts title="Web / Capacitor / PWA"
// getReferralCode(): Promise<string | null>
const code = await InfluTo.getReferralCode();
```
<!-- /tabs -->

Reads `@influto/influto_code`. This is the code `reportPurchase` sends by default.

## getCodeKind

React Native 1.7.0+. What the stored code does for the user: `referral` (a creator's code), `tracking` (one of your [tracking codes](https://docs.influ.to/platform/create-campaign.md#tracking-campaigns) — attribution only) or `free_access`; null when no code is stored. Skip referral offers when it is `tracking`. No request.

```tsx title="React Native / Expo"
// getCodeKind(): Promise<'referral' | 'tracking' | 'free_access' | null>
const kind = await InfluTo.getCodeKind();
```

## getPrefilledCode

Returns the stored code only when this install is attributed — use it to prefill a code field. No request.

<!-- tabs -->
```tsx title="React Native / Expo"
// getPrefilledCode(): Promise<string | null>
const prefill = await InfluTo.getPrefilledCode();
```
```swift title="iOS (Swift)"
// static func getPrefilledCode() async -> String?
let prefill = await InfluTo.getPrefilledCode()
```
```kotlin title="Android (Kotlin)"
// fun getPrefilledCode(): String?   (not suspend)
val prefill = InfluTo.getPrefilledCode()
```
```dart title="Flutter (Dart)"
// Future<String?> getPrefilledCode()
final prefill = await InfluTo.instance.getPrefilledCode();
```
```ts title="Web / Capacitor / PWA"
// getPrefilledCode(): Promise<string | null>
const prefill = await InfluTo.getPrefilledCode();
```
<!-- /tabs -->

Reads the stored attribution: the code when `attributed` is true (from a link or an applied code), otherwise null.

## validateCode

Checks a code the user typed, without applying it (`POST /sdk/validate-code`). Matches creator codes and free-access codes.

<!-- tabs -->
```tsx title="React Native / Expo"
// validateCode(code: string): Promise<CodeValidationResult>
const check = await InfluTo.validateCode(input);
if (!check.valid) showError(check.error_code);
```
```swift title="iOS (Swift)"
// static func validateCode(_ code: String) async -> CodeValidationResult
let check = await InfluTo.validateCode(input)
if !check.valid { print(check.errorCode ?? "") }
```
```kotlin title="Android (Kotlin)"
// suspend fun validateCode(code: String): CodeValidationResult
val check = InfluTo.validateCode(input)
if (!check.valid) Log.d("Code", check.errorCode?.name ?: "")
```
```dart title="Flutter (Dart)"
// Future<CodeValidationResult> validateCode(String code)
final check = await InfluTo.instance.validateCode(input);
if (!check.valid) debugPrint(check.errorCode);
```
```ts title="Web / Capacitor / PWA"
// validateCode(code: string): Promise<CodeValidationResult>
const check = await InfluTo.validateCode(input);
if (!check.valid) showError(check.error_code);
```
<!-- /tabs -->

Returns a [CodeValidationResult](#codevalidationresult).

- Nothing is stored and RevenueCat isn't touched.
- A free-access code comes back valid with `campaign_type` `FREE_ACCESS` and the campaign name `Free Access`.
- For creator codes, `influencer.name` and the `message` text ("Valid code! Referred by …") contain the creator's personal name. Don't show them unless your creators agreed.
- Fail-soft: before `initialize` or on a network error, returns `{ valid: false, error_code: "NETWORK_ERROR" }`.

## setReferralCode

Applies a code: stores it locally as a `manual_entry` attribution, sets the RevenueCat attributes, and records it with InfluTo (`POST /sdk/set-referral-code`). For free-access codes, this is the call that grants access.

<!-- tabs -->
```tsx title="React Native / Expo"
// setReferralCode(code: string, appUserId?: string): Promise<SetCodeResult>
const result = await InfluTo.setReferralCode(code, userId);
if (result.grantsAccess) unlockPremium();
```
```swift title="iOS (Swift)"
// static func setReferralCode(_ code: String, appUserId: String? = nil) async -> SetCodeResult
let result = await InfluTo.setReferralCode(code, appUserId: userID)
if result.grantsAccess == true { unlockPremium() }
```
```kotlin title="Android (Kotlin)"
// suspend fun setReferralCode(code: String, appUserId: String? = null): SetCodeResult
val result = InfluTo.setReferralCode(code, userId)
if (result.grantsAccess == true) unlockPremium()
```
```dart title="Flutter (Dart)"
// Future<SetCodeResult> setReferralCode(String code, {String? appUserId})
final result = await InfluTo.instance.setReferralCode(code, appUserId: userId);
if (result.grantsAccess == true) unlockPremium();
```
```ts title="Web / Capacitor / PWA"
// setReferralCode(code: string, appUserId?: string): Promise<SetCodeResult>
const result = await InfluTo.setReferralCode(code, userId);
if (result.grantsAccess) unlockPremium();
```
<!-- /tabs -->

Returns a [SetCodeResult](#setcoderesult).

- **Only an accepted code is kept.** When the server answers `success: true`, the SDK stores the code (as the server matched it, look-alike characters corrected), records the referral and writes the RevenueCat attributes. A rejected code leaves nothing behind. Older versions stored the code before the answer (before React Native 1.6.1, iOS/Android/Flutter 1.1.1, web 1.0.1). For codes users type, [`applyCode`](#applycode) validates first and returns readable error codes.
- **Free-access codes need a user ID.** `appUserId` defaults to the user from `identifyUser` (React Native 1.6.1 and iOS/Android/Flutter 1.1.1 or later; the web SDK always did). With no user at all the server answers `success: false` ("Could not identify your account"). iOS, Android and Flutter also store a passed `appUserId` as the identified user.
- If this creator's link already attributed an install from the same IP address within the attribution window, the server answers `success: true` with the message "Code already attributed from link click" and records nothing new.
- An unknown or inactive code is a `404` from the server, which the SDK returns as `success: false`.
- Gate premium on [`checkAccess`](#checkaccess) (or the store entitlement); `grantsAccess` is for unlocking immediately.

## applyCode

The usual call for a typed code: runs `validateCode`, and if the code is valid, `setReferralCode`.

<!-- tabs -->
```tsx title="React Native / Expo"
// applyCode(code: string, appUserId?: string): Promise<CodeValidationResult & { applied?: boolean }>
const result = await InfluTo.applyCode(code, userId);
if (result.applied && result.campaign?.campaign_type === 'FREE_ACCESS') {
  const { hasAccess } = await InfluTo.checkAccess(userId);
  if (hasAccess) unlockPremium();
}
```
```swift title="iOS (Swift)"
// static func applyCode(_ code: String, appUserId: String? = nil) async -> CodeValidationResult
let result = await InfluTo.applyCode(code, appUserId: userID)
if result.applied == true, result.campaign?.campaignType == "FREE_ACCESS" {
    let access = await InfluTo.checkAccess(appUserId: userID)
    if access.hasAccess { unlockPremium() }
}
```
```kotlin title="Android (Kotlin)"
// suspend fun applyCode(code: String, appUserId: String? = null): CodeValidationResult
val result = InfluTo.applyCode(code, userId)
if (result.applied == true && result.campaign?.campaignType == "FREE_ACCESS") {
    if (InfluTo.checkAccess(userId).hasAccess) unlockPremium()
}
```
```dart title="Flutter (Dart)"
// Future<CodeValidationResult> applyCode(String code, {String? appUserId})
final result = await InfluTo.instance.applyCode(code, appUserId: userId);
if (result.applied == true && result.campaign?.campaignType == 'FREE_ACCESS') {
  final access = await InfluTo.instance.checkAccess(appUserId: userId);
  if (access.hasAccess) unlockPremium();
}
```
```ts title="Web / Capacitor / PWA"
// applyCode(code: string, appUserId?: string): Promise<CodeValidationResult & { applied?: boolean }>
const result = await InfluTo.applyCode(code, userId);
if (result.applied && result.campaign?.campaign_type === 'FREE_ACCESS') {
  const { hasAccess } = await InfluTo.checkAccess(userId);
  if (hasAccess) unlockPremium();
}
```
<!-- /tabs -->

- Returns the validation result plus `applied`: `true` when `setReferralCode` succeeded, `false` when the code was invalid or applying it failed.
- It does **not** return the free-access fields (`freeAccess`, `grantsAccess`, `entitlement`, `expiresAt`). To react to a free-access code, check `campaign_type` / `campaignType` for `FREE_ACCESS` and then call `checkAccess`, as above — or call `validateCode` and `setReferralCode` yourself and read `grantsAccess`.

## checkAccess

Asks InfluTo whether this user currently has free access from a free-access code (`GET /sdk/access`). Works the same for RevenueCat and store-direct apps.

<!-- tabs -->
```tsx title="React Native / Expo"
// checkAccess(appUserId?: string): Promise<AccessResult>
const premium = entitlementActive || (await InfluTo.checkAccess(userId)).hasAccess;
```
```swift title="iOS (Swift)"
// static func checkAccess(appUserId: String? = nil) async -> AccessResult
let access = await InfluTo.checkAccess(appUserId: userID)
let premium = entitlementActive || access.hasAccess
```
```kotlin title="Android (Kotlin)"
// suspend fun checkAccess(appUserId: String? = null): AccessResult
val premium = entitlementActive || InfluTo.checkAccess(userId).hasAccess
```
```dart title="Flutter (Dart)"
// Future<AccessResult> checkAccess({String? appUserId})
final premium = entitlementActive || (await InfluTo.instance.checkAccess(appUserId: userId)).hasAccess;
```
```ts title="Web / Capacitor / PWA"
// checkAccess(appUserId?: string): Promise<AccessResult>
const premium = entitlementActive || (await InfluTo.checkAccess(userId)).hasAccess;
```
<!-- /tabs -->

Returns an [AccessResult](#accessresult).

- Uses `appUserId`, or the ID stored by `identifyUser` / `setReferralCode`. With no user ID it returns `hasAccess: false` without a request.
- **Caching:** a positive result is cached for 5 minutes under `@influto/access` (iOS, Android and Flutter also keep it in memory). A negative result is never cached, so a code redeemed a moment ago shows up on the next call.
- The server decides: seat limits and expiry are enforced there, and blocking or expiring a code removes access for everyone who redeemed it once their cached result expires.
- Recommended premium gate: your store or RevenueCat entitlement **or** `checkAccess().hasAccess`.
- Fail-soft: any error returns `hasAccess: false`. `clearAttribution` doesn't clear it.

## reportPurchase

Store-direct only. Sends the store's signed proof of a purchase so InfluTo can verify it with Apple or Google and record the commission (`POST /sdk/purchase`). If automatic capture is on, you don't call this — use one reporting path, not both.

<!-- tabs -->
```tsx title="React Native / Expo"
// reportPurchase(options: ReportPurchaseOptions): Promise<PurchaseResult>
// { platform?, signedTransaction?, purchaseToken?, productId?, price?, currency?, appUserId?, referralCode? }
await InfluTo.reportPurchase({ platform: 'ios', signedTransaction: jws });          // StoreKit 2 JWS
await InfluTo.reportPurchase({ platform: 'android', purchaseToken });              // Play Billing token
```
```swift title="iOS (Swift)"
// static func reportPurchase(verification: VerificationResult<Transaction>, appUserId: String? = nil,
//                            referralCode: String? = nil) async throws -> PurchaseResult
// static func reportPurchase(jws: String, appUserId: String? = nil,
//                            referralCode: String? = nil) async throws -> PurchaseResult
let outcome = try await product.purchase(options: [.appAccountToken(InfluTo.appAccountToken(forUserID: userID))])
if case .success(let verification) = outcome {
    _ = try await InfluTo.reportPurchase(verification: verification, appUserId: userID)
    // finish the transaction as usual
}
```
```kotlin title="Android (Kotlin)"
// suspend fun reportPurchase(purchaseToken: String, appUserId: String? = null, referralCode: String? = null,
//                            productId: String? = null, price: Double? = null, currency: String? = null): PurchaseResult
InfluTo.reportPurchase(purchaseToken = purchase.purchaseToken)                       // subscription
InfluTo.reportPurchase(purchaseToken = purchase.purchaseToken,
                       productId = "coins_100", price = 4.99, currency = "USD")       // one-time product
```
```dart title="Flutter (Dart)"
// Future<PurchaseResult> reportPurchase({required String platform, String? signedTransaction,
//     String? purchaseToken, String? productId, double? price, String? currency,
//     String? appUserId, String? referralCode})
await InfluTo.instance.reportPurchase(platform: 'android', purchaseToken: token);
```
```ts title="Web / Capacitor / PWA"
// reportPurchase(options: ReportPurchaseOptions): Promise<PurchaseResult>
await InfluTo.reportPurchase({ platform: 'android', purchaseToken });
```
<!-- /tabs -->

Returns a [PurchaseResult](#purchaseresult).

| Option | Meaning |
|---|---|
| `platform` | `ios` or `android`. Defaults to the current platform on React Native and in Capacitor/Cordova; required on Flutter and in a plain browser. iOS and Android set it themselves. |
| `signedTransaction` | iOS: the StoreKit 2 `jwsRepresentation` (the signed JWS, not the decoded JSON). The iOS SDK takes the `VerificationResult` or the JWS string. |
| `purchaseToken` | Android: the Play Billing `purchaseToken`. |
| `productId`, `price`, `currency` | Android one-time products only: the product ID (routes the purchase to one-time validation) and the price paid with its ISO currency, from `ProductDetails`. Omit them for subscriptions. |
| `appUserId` | Defaults to the ID from `identifyUser`. |
| `referralCode` | Defaults to the stored code, so the first transaction binds to the referral. |

- **Throws** on any error: `400` while the platform isn't switched to store-direct (so it's safe to ship first) or when the proof fails verification, `409` for an Android one-time purchase that isn't in the PURCHASED state yet, `503` when the currency rate is unavailable — retry later. Error types per platform are in [Limits and errors](https://docs.influ.to/reference/limits-and-errors.md#sdk-error-types).
- Reporting the same purchase twice is safe; the server keys purchases on Apple's original transaction ID and Google's purchase token.
- iOS: `InfluTo.appAccountToken(forUserID:)` gives a stable token to pass to `product.purchase(options:)` — see [below](#ios-appaccounttokenforuserid).

## Automatic purchase capture

On store-direct platforms the SDKs can report purchases for you. Capture starts only when `/sdk/init` returns `store_direct: true` for the platform and `autoCapture` isn't `false`, so RevenueCat apps are never affected. It also back-fills existing purchases once, and remembers what it sent so nothing is reported twice.

| Platform | Needs | Start / stop | One-shot back-sync |
|---|---|---|---|
| React Native | `expo-iap` or `react-native-iap` installed | Starts in `initialize`; `enableAutoPurchaseCapture({ backSync?, oneTimeProductIds? })`, `disableAutoPurchaseCapture()` | `syncExistingPurchases()` |
| iOS | Nothing (StoreKit 2, iOS 16+) | Starts in `initialize`; `startPurchaseObservation()`, `stopPurchaseObservation()` | `syncExistingPurchases()` |
| Android | `to.influ:android-sdk-billing` | Starts in `initialize`; `InfluToBilling.startObservation(context, oneTimeProductIds)`, `InfluToBilling.stopObservation()` | `InfluToBilling.syncExistingPurchases(context)` |
| Flutter | `influto_iap` | You start it: `InfluToPurchaseObserver(oneTimeProductIds: …).enable()` after `initialize`; `disable()` | `syncExisting()` |
| Web | A `purchaseSource` | Starts in `initialize`; `enableAutoPurchaseCapture(source?, opts?)`, `disableAutoPurchaseCapture()` | `syncExistingPurchases()` |

<!-- tabs -->
```tsx title="React Native / Expo"
// enableAutoPurchaseCapture(opts?: { backSync?: boolean; oneTimeProductIds?: string[] }): Promise<PurchaseSyncResult>
// disableAutoPurchaseCapture(): void
// syncExistingPurchases(): Promise<PurchaseSyncResult>
const { fetched, sent, failed } = await InfluTo.syncExistingPurchases();
```
```swift title="iOS (Swift)"
// static func startPurchaseObservation() async
// static func stopPurchaseObservation() async
// @discardableResult static func syncExistingPurchases() async -> PurchaseSyncResult
let sync = await InfluTo.syncExistingPurchases()
```
```kotlin title="Android (Kotlin)"
// to.influ.sdk.billing.InfluToBilling (artifact to.influ:android-sdk-billing)
// fun startObservation(context: Context, oneTimeProductIds: Set<String> = emptySet())
// fun stopObservation()
// suspend fun syncExistingPurchases(context: Context): PurchaseSyncResult
// suspend fun report(context: Context, purchase: Purchase, oneTime: Boolean = false,
//                    price: Double? = null, currency: String? = null): Boolean
val sync = InfluToBilling.syncExistingPurchases(applicationContext)
```
```dart title="Flutter (Dart)"
// package:influto_iap/influto_iap.dart
// InfluToPurchaseObserver({InAppPurchase? iap, Set<String> oneTimeProductIds = const {}, bool debug = false})
// Future<PurchaseSyncResult> enable({bool backSync = true}); void disable(); Future<PurchaseSyncResult> syncExisting()
final observer = InfluToPurchaseObserver(oneTimeProductIds: {'coins_100'});
final sync = await observer.enable();
```
```ts title="Web / Capacitor / PWA"
// enableAutoPurchaseCapture(source?: PurchaseSource, opts?: { backSync?: boolean; oneTimeProductIds?: string[] }): Promise<PurchaseSyncResult>
// disableAutoPurchaseCapture(): void
// syncExistingPurchases(): Promise<PurchaseSyncResult>
import { capgoNativePurchasesSource } from '@influto/web/capacitor';

await InfluTo.initialize({ apiKey: 'it_…', purchaseSource: capgoNativePurchasesSource(NativePurchases) });
```
<!-- /tabs -->

- The back-sync returns a [PurchaseSyncResult](#purchasesyncresult).
- Android: `InfluToBilling.report(context, purchase, …)` reports a `Purchase` from your own `BillingClient` without a second client; it returns `true` when the purchase was newly reported. `startObservation` runs its own `BillingClient` — use it only when nothing else handles billing.
- Flutter: the observer checks `InfluTo.instance.autoCaptureEnabled`, so call `enable()` after `initialize` has finished.
- Web purchase sources: `capgoNativePurchasesSource(NativePurchases, opts?)` from `@influto/web/capacitor`, `cordovaPurchaseSource(store, opts?)` from `@influto/web/cordova`, and `digitalGoodsSource(opts?)` from `@influto/web/pwa` for Google Play in a Trusted Web Activity. The Digital Goods API has no purchase event, so call `syncExistingPurchases()` after each checkout.
- Android one-time products: list them in `oneTimeProductIds`; a Play purchase doesn't say whether it's a subscription.

## clearAttribution

Forgets the local attribution. For testing; there's no need to call it on logout.

<!-- tabs -->
```tsx title="React Native / Expo"
// clearAttribution(): Promise<void>
await InfluTo.clearAttribution();
```
```swift title="iOS (Swift)"
// static func clearAttribution() async
await InfluTo.clearAttribution()
```
```kotlin title="Android (Kotlin)"
// fun clearAttribution()   (not suspend)
InfluTo.clearAttribution()
```
```dart title="Flutter (Dart)"
// Future<void> clearAttribution()
await InfluTo.instance.clearAttribution();
```
```ts title="Web / Capacitor / PWA"
// clearAttribution(): Promise<void>
await InfluTo.clearAttribution();
```
<!-- /tabs -->

- Removes `@influto/attribution`, `@influto/influto_code` and `@influto/app_user_id`. The web SDK removes the attribution, the code and `@influto/launch_code`, and keeps the user ID.
- Doesn't touch the server, the per-install ID, the `checkAccess` cache or the list of reported purchases.
- The next `checkAttribution` asks the server again. Within the attribution window the server returns the same answer for a device that already claimed a click, so test a fresh referral with a fresh install.

## Web-only helpers

`@influto/web` adds a few methods for runtimes where a referral arrives through a URL.

```ts
// captureLaunchCode(url?: string): Promise<LaunchCode | null>
// handleLaunchUrl(url: string): Promise<LaunchCode | null>
// captureInstallReferrer(referrer: string | null | undefined): Promise<LaunchCode | null>
// getLaunchCode(): Promise<LaunchCode | null>
// attachRevenueCat(binding: RevenueCatBinding | null): void
// getInitResult(): InitResult | null
// isInitialized: boolean   (getter)
import InfluTo from '@influto/web';
import { listenForCapacitorLaunchUrls } from '@influto/web/capacitor';

await listenForCapacitorLaunchUrls(InfluTo);          // forwards appUrlOpen + the cold-start URL
await InfluTo.captureInstallReferrer(referrerString); // Android, first launch, before checkAttribution
```

| Helper | What it does |
|---|---|
| `captureLaunchCode(url?)` | Reads `influto_code` (and `influto_click`) from a URL — by default the current page — and stores it under `@influto/launch_code` for `checkAttribution`. Runs inside `initialize` unless `captureLaunchCode: false`. When it reads the current page, it also removes the parameters from the address bar (unless `cleanUrl: false`). A captured code replaces a stored organic result. |
| `handleLaunchUrl(url)` | The same, for deep-link handlers (Capacitor `appUrlOpen`, Cordova custom schemes). `listenForCapacitorLaunchUrls(sdk, App?)` wires it for you and returns a function that removes the listener. |
| `captureInstallReferrer(referrer)` | Takes the Google Play Install Referrer string (from `@capgo/capacitor-install-referrer` or `cordova-play-install-referrer`). InfluTo's referral links put the code and click ID there, so Android attribution becomes exact. Call it once on first launch, before `checkAttribution`. |
| `getLaunchCode()` | The captured launch code, if any. |
| `attachRevenueCat(binding)` | Sets or replaces the RevenueCat binding after `initialize`. |
| `getInitResult()`, `isInitialized` | The last `/sdk/init` response, and whether `initialize` succeeded. |
| `createInfluTo()` | A separate SDK instance (tests, several apps on one page). Most apps use the default export. |

`LaunchCode` is `{ code, clickId?, capturedAt }`. The root package also exports `InfluToApiError`, `STORAGE_KEYS`, `SDK_VERSION` and the adapter helpers; the React component and hook are documented under [UI components](https://docs.influ.to/reference/ui.md#web-react).

## iOS: appAccountToken(forUserID:)

Returns a stable UUID for a user ID, to pass as the StoreKit `appAccountToken` when the user buys. Not async, no request.

```swift
// static func appAccountToken(forUserID userID: String) -> UUID
let token = InfluTo.appAccountToken(forUserID: userID)
let outcome = try await product.purchase(options: [.appAccountToken(token)])
```

The same user ID always gives the same UUID (derived from a SHA-256 of the ID, in UUID version 5 layout), so the purchase stays tied to the user across renewals.

## Result types

### AttributionResult

Returned by `checkAttribution`. Same field names on every platform.

| Field | Type | Meaning |
|---|---|---|
| `attributed` | boolean | Whether a creator referred this install |
| `referralCode` | string? | The creator's code |
| `attributionMethod` | string? | `link_param`, `ip_device_match` or `manual_entry` |
| `clickedAt` | string? | ISO 8601 time of the referral click (or of the manual entry) |
| `message` | string? | Server or SDK explanation, for example "No matching referral click found (organic install)" |
| `clickId` | string? | Web only: the claimed click |

### CodeValidationResult

Returned by `validateCode` and `applyCode`. React Native and web keep snake_case for the nested fields; iOS, Android and Flutter use camelCase.

| Field (RN / web) | iOS / Android / Flutter | Meaning |
|---|---|---|
| `valid` | `valid` | Whether the code is an active creator code or a valid free-access code |
| `code` | `code` | The matched code as stored by InfluTo |
| `campaign.id`, `.name`, `.description` | same | The campaign. Free-access codes: name `Free Access` |
| `campaign.commission_percentage` | `campaign.commissionPercentage` | Creator commission (0 for free-access codes) |
| `campaign.campaign_type` | `campaign.campaignType` | `public`, `private`, `invite_only`, or `FREE_ACCESS` |
| `influencer.name`, `.social_handle`, `.follower_count` | `influencer.name`, `.socialHandle`, `.followerCount` | The creator's details — personal data, hidden by default in the UI components. `null` for free-access codes |
| `custom_data` | `customData` | Extra data attached to a free-access code |
| `message` | `message` | Success text; for creator codes it includes the creator's name |
| `error` | `error` | Error text |
| `error_code` | `errorCode` | See the table below. Android: enum `CodeErrorCode`, with `UNKNOWN` for unrecognized values |
| `applied` | `applied` | `applyCode` only: whether the code was applied |

| Error code | When |
|---|---|
| `INVALID_FORMAT` | Fewer than 4 or more than 20 characters after cleanup |
| `CODE_NOT_FOUND` | No active creator code or free-access code matches ("Code not found or inactive") |
| `CODE_EXPIRED` | A free-access code that expired or has no seats left |
| `NETWORK_ERROR` | Set by the SDK: the request failed, or the SDK isn't initialized |

### SetCodeResult

Returned by `setReferralCode`. camelCase on every platform.

| Field | Type | Meaning |
|---|---|---|
| `success` | boolean | Whether the server recorded the code |
| `code` | string? | The matched code |
| `message` | string | Server or SDK message (optional on iOS, Android and Flutter) |
| `campaign` | `{ id, name }`? | The campaign the code belongs to |
| `freeAccess` | boolean? | `true` when it's a free-access code |
| `grantsAccess` | boolean? | `true` when the server granted free access to this user |
| `entitlement` | string? | The RevenueCat entitlement mirrored for the grant, when the app has RevenueCat access set up |
| `expiresAt` | string? | ISO 8601 end of the free access; absent for open-ended access |

### AccessResult

Returned by `checkAccess`. camelCase on every platform.

| Field | Type | Meaning |
|---|---|---|
| `hasAccess` | boolean | Whether InfluTo grants this user free access now |
| `source` | string? | `comp` when access comes from a free-access code |
| `entitlement` | string? | The mirrored RevenueCat entitlement, if any |
| `expiresAt` | string? | ISO 8601 end of the access; absent when open-ended |
| `code` | string? | The free-access code that granted it |

### PurchaseResult

Returned by `reportPurchase`.

| Field (RN / web) | iOS / Android / Flutter | Meaning |
|---|---|---|
| `success` | `success` | `true` when the purchase was verified and processed |
| `validated` | `validated` | `apple` or `google` — a string, not a boolean |
| `environment` | `environment` | `PRODUCTION` or `SANDBOX` |
| `event_type` | `eventType` | The event recorded, for example `INITIAL_PURCHASE` or `NON_RENEWING_PURCHASE` |
| `result` | `result` | The processing result, for diagnostics |
| `duplicate`, `recorded` | — | Declared in the web type only (the server always sends them): the purchase was already recorded, or was recorded by this call |

### PurchaseSyncResult

Returned by the back-sync methods: `{ fetched, sent, failed }` — purchases the store returned, newly reported ones (already-reported purchases count as neither sent nor failed), and reports that threw. iOS and Android add `success`, which is `true` when nothing failed.

### Campaign

Returned by `getActiveCampaigns`: `id`, `name`, `description`, and `commission_percentage` (React Native, web) or `commissionPercentage` (iOS, Android, Flutter).

## Local storage

The SDKs keep a few values on the device, under the same keys on every platform: AsyncStorage on React Native, a `UserDefaults` suite (`com.influto.sdk`) on iOS, the `influto_prefs` SharedPreferences file on Android, `shared_preferences` on Flutter, and `localStorage` (or the storage adapter you pass) on web.

| Key | Holds | Cleared by `clearAttribution` |
|---|---|---|
| `@influto/attribution` | The stored attribution result (JSON) | Yes |
| `@influto/influto_code` | The referral or free-access code | Yes |
| `@influto/app_user_id` | The identified user ID | Yes (not on web) |
| `@influto/initialized` | `"true"` after a successful `initialize` | No |
| `@influto/install_id` | A random per-install ID, sent with `track-install` so installs are counted once | No |
| `@influto/access` | The cached positive `checkAccess` result (5 minutes) | No |
| `@influto/launch_code` | Web only: a code captured from the launch URL or Install Referrer | Yes |
| `@influto/reported_purchases` | React Native, Flutter and web: purchases already reported by automatic capture | No |
| `@influto/sent_purchases` | iOS: purchases already reported by automatic capture | No |

On Android, `android-sdk-billing` keeps its list of reported purchases in a separate preferences file, `influto_billing_sync_prefs`. Uninstalling a native app removes all of these, which is why a reinstall counts as a new install.

---

<!-- https://docs.influ.to/reference/ui -->
# Referral code input components

> The ready-made referral code fields for React Native, SwiftUI, Jetpack Compose, Flutter and React — props, defaults, theming, privacy and building your own.

Every InfluTo SDK ships a ready-made field where users type a creator's referral code or a free-access code. It prefills the code when a referral link brought the user, checks it with InfluTo, and applies it. Use it as is, or build your own field on [`validateCode`](https://docs.influ.to/reference/sdk.md#validatecode) and [`applyCode`](https://docs.influ.to/reference/sdk.md#applycode) — see [the last section](#build-your-own-field) and the [referral code guide](https://docs.influ.to/guides/referral-codes.md).

## Which component

| Platform | Component | Import | Where it ships |
|---|---|---|---|
| React Native / Expo | `ReferralCodeInput` | `import { ReferralCodeInput } from '@influto/react-native-sdk/ui'` | In `@influto/react-native-sdk` |
| iOS (SwiftUI) | `InfluToReferralCodeInput` | `import InfluTo` | In the Swift package (iOS 16+) |
| Android (Jetpack Compose) | `InfluToReferralCodeInput` | `import to.influ.sdk.ui.InfluToReferralCodeInput` | Separate artifact `to.influ:android-sdk-ui` (Material 3) |
| Flutter | `ReferralCodeInput` | `import 'package:influto/influto.dart'` | In `influto` |
| Web (React) | `ReferralCodeInput`, `useInfluToAttribution` | `import { ReferralCodeInput } from '@influto/web/react'` | In `@influto/web` (needs React 17+) |

All of them need [`initialize`](https://docs.influ.to/reference/sdk.md#initialize) to have finished first.

## How they behave

| | React Native | iOS, Android, Flutter | Web (React) |
|---|---|---|---|
| Prefill | `getPrefilledCode()` on mount (`autoPrefill`) | Same (`autoPrefill`) | Same (`prefill`) |
| Checks the code | When the field loses focus, and on the button | While the user types: from 3 characters, 450 ms after the last keystroke | On submit |
| Applies the code | As soon as a check finds it valid (`setReferralCode`) | When the user taps Apply (`applyCode`); the button is enabled only for a valid code | On submit (`applyCode`) |
| Callbacks | `onValidated`, `onApplied`, `onSkip` | `onValidated`, `onApplied` | `onCodeApplied`, `onInvalid` |
| Input | Uppercased, up to 20 characters | Uppercased; letters, digits, `-` and `_` (Flutter: up to 20) | Uppercased |

When a code is rejected, the components show the result's `error` text — the server's English message, such as "Code not found or inactive", or the SDK's "Network error or invalid response" — and fall back to your invalid label only when there's none (Android shows "This code has expired" for an expired code). For fully localized messages, build your own field and map `error_code` yourself.

> [!WARNING]
> The iOS, Android and Flutter components drop `_` as the user types, but creator codes may contain underscores (`A–Z 0–9 _ -`). If any of your creators use one, build your own field.

## Privacy defaults

By default each component shows only the field and whether the code is valid. Two props, both `false` by default, add more:

- `showCampaignName` — shows the campaign's name (React Native also shows its description).
- `showReferrerName` — shows the creator's personal name ("Referred by …"). Turn it on only if your creators agreed to be named.

React Native shows them once the code is valid (which is also when it's applied); iOS, Android and Flutter after the user taps Apply; web in the success message. The raw `validateCode` result always carries the creator's name in `influencer.name` and in `message` — keep those off screen in your own UI too.

## React Native

```tsx
import { ReferralCodeInput } from '@influto/react-native-sdk/ui';

<ReferralCodeInput
  appUserId={userId}
  labels={{ title: 'Got a code?', validateButton: 'Apply' }}
  colors={{ primary: '#111827' }}
  onApplied={(result) => {
    if (result.campaign?.campaign_type === 'FREE_ACCESS') refreshPremium();
  }}
  onSkip={() => navigation.navigate('Paywall')}
/>
```

| Prop | Type | Default | What it does |
|---|---|---|---|
| `appUserId` | `string` | identified user | Passed to `setReferralCode`. Free-access codes need a user. |
| `autoPrefill` | `boolean` | `true` | Fills in the code when the install is attributed. |
| `autoValidate` | `boolean` | `false` | Checks (and so applies) a prefilled code on mount. |
| `validateOnBlur` | `boolean` | `true` | Checks the code when the field loses focus. A valid code is applied right away. |
| `showSkipButton` | `boolean` | `true` | Shows a Skip button — only when `onSkip` is also set. |
| `showCampaignName` | `boolean` | `false` | See [Privacy defaults](#privacy-defaults). |
| `showReferrerName` | `boolean` | `false` | See [Privacy defaults](#privacy-defaults). Also swaps the success text for the server's "Valid code! Referred by …". |
| `onValidated` | `(result: CodeValidationResult) => void` | — | After every check, valid or not (including network errors). |
| `onApplied` | `(result: CodeValidationResult) => void` | — | After a valid code was applied. Receives the validation result. |
| `onSkip` | `() => void` | — | When the user taps Skip. |
| `colors`, `fonts`, `labels`, `style` | objects | see below | Theming. |

Codes shorter than 4 characters are rejected in the component with `INVALID_FORMAT` before any request.

### Theming

| `colors` key | Default |
|---|---|
| `primary` | `#3B82F6` (button, prefilled hint) |
| `success` | `#10B981` |
| `error` | `#EF4444` |
| `text` | `#1F2937` |
| `textSecondary` | `#6B7280` |
| `border` | `#D1D5DB` |
| `inputBackground` | `#F9FAFB` |
| `background` | `#FFFFFF` — accepted but not applied; set `style.container.backgroundColor` instead |

| `fonts` key | Default |
|---|---|
| `family` | `System` on iOS, `Roboto` on Android |
| `sizeTitle` | `18` |
| `sizeInput` | `16` |
| `sizeButton` | `16` |
| `sizeMessage` | `14` |

| `labels` key | Default |
|---|---|
| `title` | `Have a promo code?` |
| `subtitle` | `Add the code you received from a creator or friend` |
| `placeholder` | `Enter code (e.g., FITGURU30)` |
| `validateButton` | `Apply Code` |
| `skipButton` | `Skip` |
| `validatingMessage` | `Validating code...` |
| `validMessage` | `Code applied successfully!` |
| `invalidMessage` | `Invalid code. Please try again.` |
| `errorMessage` | `Unable to validate code. Check your connection.` |
| `prefilledMessage` | `Code detected from your referral link` |

`style` takes React Native styles for `container`, `titleContainer`, `title`, `subtitle`, `inputContainer`, `input`, `buttonContainer`, `validateButton`, `validateButtonText`, `skipButton`, `skipButtonText`, `messageContainer` and `messageText`. They're applied on top of the defaults; the container is a white card with 20 pt padding, rounded corners and a shadow.

## iOS (SwiftUI)

```swift
import SwiftUI
import InfluTo

struct CodeStep: View {
    let userID: String?

    var body: some View {
        InfluToReferralCodeInput(
            appUserId: userID,
            title: "Got a code?",
            onApplied: { result in
                if result.campaign?.campaignType == "FREE_ACCESS" { refreshPremium() }
            }
        )
    }
}
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `appUserId` | `String?` | identified user | Passed to `applyCode`. Free-access codes need a user. |
| `autoPrefill` | `Bool` | `true` | Fills in the code when the install is attributed. |
| `autoValidate` | `Bool` | `false` | Checks a prefilled code right away. |
| `showCampaignName` | `Bool` | `false` | See [Privacy defaults](#privacy-defaults). |
| `showReferrerName` | `Bool` | `false` | See [Privacy defaults](#privacy-defaults). |
| `title` | `String?` | `nil` | Optional heading above the field. |
| `labels` | `InfluToReferralCodeInput.Labels` | see below | Texts. |
| `onValidated` | `((CodeValidationResult) -> Void)?` | `nil` | After every check. |
| `onApplied` | `((CodeValidationResult) -> Void)?` | `nil` | After the user taps Apply and the code was recorded (`result.applied` is true). |

`Labels` has four `var`s: `placeholder` (`Referral code`), `apply` (`Apply`), `valid` (`Code applied`) and `invalid` (`This code isn't valid`):

```swift
var labels = InfluToReferralCodeInput.Labels()
labels.placeholder = "Promo code"
labels.apply = "Use code"
```

It's built from a standard `TextField`, `Button` and system text styles, with green and red for the valid and invalid states. Style the surrounding view with ordinary SwiftUI modifiers.

## Android (Jetpack Compose)

```kotlin file="build.gradle.kts"
dependencies {
    implementation("to.influ:android-sdk:1.1.1")
    implementation("to.influ:android-sdk-ui:1.1.1")
}
```

```kotlin
import to.influ.sdk.ui.InfluToReferralCodeInput

InfluToReferralCodeInput(
    appUserId = userId,
    title = "Got a code?",
    onApplied = { result ->
        if (result.campaign?.campaignType == "FREE_ACCESS") refreshPremium()
    },
)
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `modifier` | `Modifier` | `Modifier` | Applied to the column that holds the field. |
| `appUserId` | `String?` | identified user | Passed to `applyCode`. Free-access codes need a user. |
| `autoPrefill` | `Boolean` | `true` | Fills in the code when the install is attributed. |
| `autoValidate` | `Boolean` | `false` | Checks a prefilled code right away. |
| `showCampaignName` | `Boolean` | `false` | See [Privacy defaults](#privacy-defaults). |
| `showReferrerName` | `Boolean` | `false` | See [Privacy defaults](#privacy-defaults). |
| `title` | `String?` | `null` | Optional heading. |
| `placeholder` | `String` | `"Referral code"` | The field's label. |
| `applyLabel` | `String` | `"Apply"` | Button text. |
| `validMessage` | `String` | `"Code applied"` | Shown under a valid code. |
| `invalidMessage` | `String` | `"This code isn't valid"` | Shown when the server gives no error text. An expired free-access code shows "This code has expired". |
| `onValidated` | `(CodeValidationResult) -> Unit` | `{}` | After every check. |
| `onApplied` | `(CodeValidationResult) -> Unit` | `{}` | After the user taps Apply and the code was recorded (`result.applied` is true). |

It's built from Material 3 `OutlinedTextField` and `Button`, so it follows your `MaterialTheme`.

## Flutter

```dart
import 'package:influto/influto.dart';

ReferralCodeInput(
  appUserId: userId,
  title: 'Got a code?',
  onApplied: (result) {
    if (result.campaign?.campaignType == 'FREE_ACCESS') refreshPremium();
  },
)
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `appUserId` | `String?` | identified user | Passed to `applyCode`. Free-access codes need a user. |
| `autoPrefill` | `bool` | `true` | Fills in the code when the install is attributed. |
| `autoValidate` | `bool` | `false` | Checks a prefilled code right away. |
| `showCampaignName` | `bool` | `false` | See [Privacy defaults](#privacy-defaults). |
| `showReferrerName` | `bool` | `false` | See [Privacy defaults](#privacy-defaults). |
| `title` | `String?` | `null` | Optional heading. |
| `placeholder` | `String` | `'Referral code'` | The field's label. |
| `applyLabel` | `String` | `'Apply'` | Button text. |
| `validMessage` | `String` | `'Code applied'` | Helper text under a valid code. |
| `invalidMessage` | `String` | `"This code isn't valid"` | Shown when the server gives no error text. |
| `onValidated` | `ValueChanged<CodeValidationResult>?` | `null` | After every check. |
| `onApplied` | `ValueChanged<CodeValidationResult>?` | `null` | After the user taps Apply and the code was recorded (`result.applied` is true). |

It uses a Material `TextField` with an outlined border and an `ElevatedButton`, so it follows your `ThemeData`.

## Web (React)

`@influto/web/react` works in React and Ionic React apps.

```tsx
import { ReferralCodeInput, useInfluToAttribution } from '@influto/web/react';

function CodeStep({ ready, userId }: { ready: boolean; userId?: string }) {
  const { loading, attribution } = useInfluToAttribution(ready);
  if (loading) return null;

  return (
    <>
      {attribution?.attributed && <p>Your creator's offer is applied.</p>}
      <ReferralCodeInput
        appUserId={userId}
        className="code-form"
        onCodeApplied={(code, result) => {
          if (result.campaign?.campaign_type === 'FREE_ACCESS') refreshPremium();
        }}
      />
    </>
  );
}
```

### ReferralCodeInput

| Prop | Type | Default | What it does |
|---|---|---|---|
| `appUserId` | `string` | — | Passed to `applyCode`. Without it, free-access codes use the ID from `identifyUser`. |
| `prefill` | `boolean` | `true` | Fills in the code when the install is attributed. |
| `showCampaignName` | `boolean` | `false` | See [Privacy defaults](#privacy-defaults). |
| `showReferrerName` | `boolean` | `false` | See [Privacy defaults](#privacy-defaults). |
| `placeholder` | `string` | `'Referral or access code'` | Input placeholder. |
| `buttonLabel` | `string` | `'Apply'` | Submit button text (shows `…` while checking). |
| `onCodeApplied` | `(code, result) => void` | — | After the code was applied. `result` is the `applyCode` result. |
| `onInvalid` | `(result) => void` | — | When the code was rejected, or valid but couldn't be applied. |
| `className`, `style` | `string`, `CSSProperties` | — | On the `<form>`. |
| `inputClassName`, `buttonClassName` | `string` | — | On the input and the button. |
| `sdk` | `InfluToWebSDK` | default instance | Use an instance from `createInfluTo()`. |

It renders an unstyled `<form>` with an input, a submit button and, after a submit, a `<span role="status">` with `Code applied` or the error (`Invalid code` when the server gives none). Style it with your classes, or target the attributes it sets: `data-influto-status` on the form (`idle`, `checking`, `valid`, `invalid`) and `data-influto-message` on the message.

### useInfluToAttribution

`useInfluToAttribution(enabled = true, sdk = InfluTo)` runs `checkAttribution()` once and returns `loading`, `attribution` (an [AttributionResult](https://docs.influ.to/reference/sdk.md#attributionresult) or `null`), `error` and `refresh()`. Pass `enabled = false` until `initialize()` has resolved — before that, `checkAttribution` throws and the hook reports it as `error`.

## Build your own field

For your own design or fully localized messages, use the SDK calls directly: check the code with `validateCode` while the user types (debounced), and apply it with `applyCode` when they submit.

<!-- tabs -->
```tsx title="React Native / Expo"
// While typing (debounced): show valid / invalid only
const check = await InfluTo.validateCode(text);
setValid(check.valid);

// On submit
const result = await InfluTo.applyCode(text, userId);
if (!result.applied) showError(result.error_code);
else if (result.campaign?.campaign_type === 'FREE_ACCESS' && (await InfluTo.checkAccess(userId)).hasAccess) unlockPremium();
```
```swift title="iOS (Swift)"
// While typing (debounced): show valid / invalid only
let check = await InfluTo.validateCode(text)
isValid = check.valid

// On submit
let result = await InfluTo.applyCode(text, appUserId: userID)
if result.applied != true {
    showError(result.errorCode)
} else if result.campaign?.campaignType == "FREE_ACCESS" {
    let access = await InfluTo.checkAccess(appUserId: userID)
    if access.hasAccess { unlockPremium() }
}
```
```kotlin title="Android (Kotlin)"
// While typing (debounced): show valid / invalid only
val check = InfluTo.validateCode(text)
isValid = check.valid

// On submit
val result = InfluTo.applyCode(text, userId)
if (result.applied != true) showError(result.errorCode)
else if (result.campaign?.campaignType == "FREE_ACCESS" && InfluTo.checkAccess(userId).hasAccess) unlockPremium()
```
```dart title="Flutter (Dart)"
// While typing (debounced): show valid / invalid only
final check = await InfluTo.instance.validateCode(text);
setState(() => isValid = check.valid);

// On submit
final result = await InfluTo.instance.applyCode(text, appUserId: userId);
if (result.applied != true) {
  showError(result.errorCode);
} else if (result.campaign?.campaignType == 'FREE_ACCESS' &&
    (await InfluTo.instance.checkAccess(appUserId: userId)).hasAccess) {
  unlockPremium();
}
```
```ts title="Web / Capacitor / PWA"
// While typing (debounced): show valid / invalid only
const check = await InfluTo.validateCode(text);
setValid(check.valid);

// On submit
const result = await InfluTo.applyCode(text, userId);
if (!result.applied) showError(result.error_code);
else if (result.campaign?.campaign_type === 'FREE_ACCESS' && (await InfluTo.checkAccess(userId)).hasAccess) unlockPremium();
```
<!-- /tabs -->

- Uppercase the input and keep only `A–Z`, `0–9`, `_` and `-`, 4–20 characters ([code rules](https://docs.influ.to/reference/limits-and-errors.md#code-format)). The SDK only trims and uppercases, and the code it stores and writes to RevenueCat is the one you pass — so a stray space or invisible character from a pasted caption must be removed here.
- Map `error_code` / `errorCode` (`INVALID_FORMAT`, `CODE_NOT_FOUND`, `CODE_EXPIRED`, `NETWORK_ERROR`) to your own localized text. `applied` can also be false for a valid code, for example a free-access code without a user ID.
- `applyCode` binds the code to the user from `identifyUser`, or the user ID you pass; free-access codes need one.
- Don't display `influencer` or `message` unless your creators agreed to be named.
- Gate premium on your store entitlement or `checkAccess().hasAccess`, not on the code result alone.

---

<!-- https://docs.influ.to/reference/http-api -->
# HTTP API reference

> The /api/sdk endpoints behind every InfluTo SDK, the RevenueCat and Google Play webhooks InfluTo receives, and where the agent REST API is documented.

The SDKs are thin clients over a small HTTP API. Use this page when your stack has no SDK, or to see what an SDK sends while you debug. If an SDK exists for your platform, use it — it also stores the attribution, sets RevenueCat attributes and de-duplicates for you. The full wire contract, including the rules every SDK follows, is at [docs.influ.to/contract.md](https://docs.influ.to/contract.md) (wire version 1.6.0).

## Basics

- **Base URL:** `https://influ.to/api`
- **Auth:** `Authorization: Bearer <SDK key>` on every request. The key starts with `it_` and is on **Setup & SDK**; one key per app covers sandbox and production. It only works on the `/api/sdk/*` endpoints of its own app. It ships inside your app, so treat it as public.
- **Format:** JSON bodies with `Content-Type: application/json`. Field names are snake_case. `/sdk/event` and `/sdk/purchase` also accept camelCase, which is what the SDKs send there.
- **Errors:** `{"detail": "…"}` with the status code. A missing or mistyped field is a `422` with the field list in `detail`. A request over the rate limit gets a plain `429` page. All codes: [Limits and errors](https://docs.influ.to/reference/limits-and-errors.md#http-status-codes-for-apisdk).
- The server reads the client IP and User-Agent from the request itself; don't put them in the body.

```bash
curl https://influ.to/api/sdk/validate-code \
  -H "Authorization: Bearer $INFLUTO_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "MAYA"}'
```

## Endpoints

| Method | Path | Purpose | SDK method |
|---|---|---|---|
| `POST` | `/sdk/init` | Start-up check; says whether the platform is store-direct | `initialize` |
| `POST` | `/sdk/track-install` | Decide whether this install was referred | `checkAttribution` |
| `POST` | `/sdk/identify` | Attach your user ID to the install | `identifyUser` |
| `POST` | `/sdk/event` | Record a custom event | `trackEvent` |
| `POST` | `/sdk/validate-code` | Check a typed code | `validateCode` |
| `POST` | `/sdk/set-referral-code` | Apply a code; redeem a free-access code | `setReferralCode` |
| `POST` | `/sdk/purchase` | Report a store purchase (store-direct) | `reportPurchase` |
| `GET` | `/sdk/access` | Whether a user has free access | `checkAccess` |
| `GET` | `/sdk/campaigns` | Active public campaigns | `getActiveCampaigns` |
| `GET` | `/sdk/attribution` | A paying user's attribution | — |
| `GET` | `/sdk/recent-conversions` | A user's recent purchase outcomes, for testing | — |

## POST /sdk/init

Call once per app start. It marks the SDK as installed on the Setup page and tells the client whether this platform uses store-direct validation.

| Field | Required | Notes |
|---|---|---|
| `app_version` | Yes | Your app's version (`"unknown"` if you don't have it) |
| `sdk_version` | Yes | Your client's version |
| `platform` | Yes | `ios`, `android` or `web` |
| `sdk_name`, `runtime` | No | Sent by the web SDK (`web`; `capacitor`, `cordova`, `twa`, `pwa` or `browser`) |

```json
{
  "app_id": "3f6c…",
  "app_name": "Your App",
  "attribution_window_hours": 24,
  "campaigns": [{ "id": "a1b2…", "name": "Launch", "description": null }],
  "store_direct": false,
  "initialized": true
}
```

`campaigns` lists every active campaign of the app. `store_direct` is `true` when this platform validates purchases directly with Apple or Google; the SDKs start automatic purchase capture only then.

## POST /sdk/track-install

Decides once per install whether a creator referred it — by the code a link carried into the app, or by link-click matching within 72 hours. Call it on first launch and store the answer; the SDKs never call it again after they have one.

| Field | Required | Notes |
|---|---|---|
| `platform` | Yes | `ios`, `android` or `web` |
| `device_id` | Recommended | A random UUID you generate once per install and persist. Installs are counted once per `device_id`. |
| `device_brand`, `device_model`, `os_version`, `screen_resolution`, `timezone`, `language` | No | Device details the SDKs send for matching. camelCase also accepted. |
| `referral_code`, `click_id` | No | From a link that carried the code into the app (`influto_code` / `influto_click` on a web app's URL, or the Play Install Referrer). The install is then attributed exactly (`link_param`). |

```json
{
  "attributed": true,
  "referral_code": "MAYA",
  "attribution_method": "ip_device_match",
  "clicked_at": "2026-10-09T08:12:44.120000",
  "click_id": "9d2e…",
  "install_recorded": true,
  "message": "Install attributed successfully"
}
```

- Organic: `{"attributed": false, "install_recorded": true, "message": "No matching referral click found (organic install)"}`.
- `install_recorded` is `false` when this `device_id` was seen before.
- A device that already claimed a click within the window gets the same answer again, with `"re_claimed": true` — so a lost response can be fetched again without taking someone else's click.
- `attribution_method`: `link_param` or `ip_device_match` (link-click matching). See [attribution](https://docs.influ.to/advanced/attribution.md).

## POST /sdk/identify

Attaches your user ID — usually the RevenueCat app user ID — to the install. When a RevenueCat event later arrives without the `influto_code` attribute, InfluTo looks for an attributed click with that user ID.

| Field | Required | Notes |
|---|---|---|
| `app_user_id` | Yes | Your user ID. Empty is a `400`. |
| `properties` | No | Object, stored for your reference |
| `device_id` (+ `platform` and the device fields) | No | Send the same `device_id` you sent to `track-install` and the server matches this exact install. Without it, it falls back to the request's IP and only uses an unambiguous, recent match. |

```json
{ "identified": true, "app_user_id": "user_123", "attribution_backfilled": true }
```

The first identify for a click wins. The same key and user identified again within 60 seconds is answered from memory with `"deduplicated": true`. This endpoint has its own, lower rate limit — 2 requests per second per IP — so call it once per launch, not in a loop.

## POST /sdk/event

Records a custom event for the dashboard funnel. It never creates a conversion or a commission.

| Field | Required | Notes |
|---|---|---|
| `event_type` / `eventType` | Yes | For example `paywall_viewed`, `trial_started` |
| `app_user_id` / `appUserId` | Yes | Your user ID |
| `properties` | No | Object |
| `referral_code` / `referralCode` | No | Code to associate |
| `event_id` / `eventId` | No | Your idempotency key — a repeat with the same ID is dropped |

```json
{ "tracked": true, "event_id": "c71a…" }
```

A dropped repeat answers `{"tracked": true, "event_id": "…", "duplicate": true, "dedup_reason": "…"}`. Besides `event_id`, the server keeps `trial_started`, `subscription_purchased` and `subscription_renewed` to one per user and property set, and drops an identical event without an `event_id` repeated within 60 seconds.

## POST /sdk/validate-code

Checks a code a user typed, against the app's active creator codes and then its free-access codes. Always `200` (unless the request itself is rejected); look at `valid`.

| Field | Required | Notes |
|---|---|---|
| `code` | Yes | The server uppercases it and drops characters outside `A–Z 0–9 _ -` |

Creator code:

```json
{
  "valid": true,
  "code": "MAYA",
  "campaign": { "id": "a1b2…", "name": "Launch", "description": null, "commission_percentage": 30.0, "campaign_type": "public" },
  "influencer": { "name": "Maya R.", "social_handle": "@maya", "follower_count": null },
  "custom_data": null,
  "message": "Valid code! Referred by Maya R."
}
```

A free-access code returns `campaign.name` `"Free Access"`, `campaign.campaign_type` `"FREE_ACCESS"`, `commission_percentage` `0`, `influencer: null` and the code's `custom_data`. `influencer` and `message` contain the creator's personal name — don't show them to users unless creators agreed.

Invalid: `{"valid": false, "error": "Code not found or inactive", "error_code": "CODE_NOT_FOUND"}`. The `error_code` values are `INVALID_FORMAT` (not 4–20 characters), `CODE_NOT_FOUND` and `CODE_EXPIRED` (a free-access code that expired or has no seats left).

## POST /sdk/set-referral-code

Applies a code for this user. For a creator code it records the attribution; for a free-access code it grants the free access.

| Field | Required | Notes |
|---|---|---|
| `code` | Yes | Same cleanup as `validate-code` |
| `app_user_id` | For free-access codes | Without it a free-access code fails with `MISSING_USER_ID` |

Creator code:

```json
{ "success": true, "code": "MAYA", "code_kind": "referral", "message": "Referral code set successfully", "campaign": { "id": "a1b2…", "name": "Launch" } }
```

`code_kind` says what the code does for the user: `referral` (a creator's code), `tracking` (one of the app's [tracking codes](https://docs.influ.to/platform/create-campaign.md#tracking-campaigns): attribution only — don't give a referral benefit) or `free_access`. It is also in the `validate-code`, `track-install` (when attributed) and `attribution` responses.

If this creator's link already attributed an install from the same IP within the window, nothing new is recorded: `"message": "Code already attributed from link click"` with `"already_attributed": true`. A new manual entry counts as a click and an install for the creator.

Free-access code:

```json
{
  "success": true,
  "code": "PRESS2026",
  "free_access": true,
  "grants_access": true,
  "already_granted": false,
  "credited_to": null,
  "entitlement": "premium",
  "access_duration_years": 1,
  "access_duration_days": 365,
  "expires_at": "2027-10-09T08:15:02",
  "rc_grant": { "attempted": true, "ok": true, "error": null },
  "message": "Free access activated — 1 year of premium."
}
```

- Access is granted in InfluTo whether or not RevenueCat is involved; `rc_grant` only reports the optional RevenueCat promotional-entitlement mirror. Gate premium on `GET /sdk/access`, not on `rc_grant`.
- Redeeming the same code again for the same user restores access inside their original window without using another seat (`already_granted: true`). After that window the code is spent for them (`CODE_EXPIRED`).
- `credited_to` is the referral code of the partner the code credits, or `null` — see [Credit a partner](https://docs.influ.to/platform/creator-access-codes.md#credit-a-partner).
- A free-access failure is still `200`, with `success: false`, `free_access: true`, and `error_code` `CODE_EXPIRED` or `MISSING_USER_ID`.
- An unknown or inactive code is `404` `{"detail": "Referral code not found or inactive"}`.

## POST /sdk/purchase

Store-direct only. Sends the store's signed proof of a purchase; InfluTo verifies it with Apple or Google, converts the price to USD at the purchase date's rate, and records it exactly like a RevenueCat event. See [store-direct](https://docs.influ.to/integrations/store-direct.md).

| Field | Required | Notes |
|---|---|---|
| `platform` | Yes | `ios` or `android` |
| `signed_transaction` / `signedTransaction` | iOS | StoreKit 2 `jwsRepresentation` (the signed JWS) |
| `purchase_token` / `purchaseToken` | Android | Play Billing `purchaseToken` |
| `product_id` / `productId` | Android one-time products | Routes the purchase to one-time validation. Omit for subscriptions. |
| `price`, `currency` | Android one-time products | Price paid (major units) and ISO currency, from `ProductDetails` — Google doesn't return a one-time price |
| `referral_code` / `referralCode` | First purchase | The stored referral code, so the purchase binds to the creator |
| `app_user_id` / `appUserId` | No | Your user ID; also makes the purchase show up in `recent-conversions` |

```json
{
  "success": true,
  "validated": "apple",
  "environment": "PRODUCTION",
  "event_type": "INITIAL_PURCHASE",
  "duplicate": false,
  "recorded": true,
  "result": { "processed": true, "event_id": "…" }
}
```

| Status | Meaning |
|---|---|
| `200` | Verified and processed. `duplicate: true` means it was already recorded — reporting twice is safe. |
| `400` | The platform isn't switched to store-direct yet (switching needs a green credential check), credentials are missing, the proof is missing, verification failed, or the platform isn't `ios`/`android`. |
| `409` | Android one-time purchase that isn't in the PURCHASED state (for example, still pending). |
| `503` | The exchange rate isn't available right now. Retry later. |

Apple purchases are keyed on the original transaction ID, Google subscriptions on the purchase token, Google one-time purchases on the order ID — so renewals and refunds found later attach to the same conversion.

## GET /sdk/access

`/sdk/access?app_user_id=user_123` — whether InfluTo currently grants this user free access from a free-access code.

```json
{ "has_access": true, "source": "comp", "entitlement": "premium", "expires_at": "2027-10-09T08:15:02", "code": "PRESS2026" }
```

Without access: `{"has_access": false, "source": null, "entitlement": null, "expires_at": null, "code": null}`. Seat limits and expiry are checked on every call; a blocked or expired code removes access. An empty `app_user_id` is a `400`.

## GET /sdk/campaigns

The app's active **public** campaigns, for showing offers in the app.

```json
[{ "id": "a1b2…", "name": "Launch", "description": null, "commission_percentage": 30.0 }]
```

## GET /sdk/attribution

`/sdk/attribution?app_user_id=user_123` — which creator a paying user is attributed to. It reads conversions, so it answers `attributed: true` only once an attributed purchase exists.

```json
{
  "attributed": true,
  "referral_code": "MAYA",
  "campaign": { "id": "a1b2…", "name": "Launch" },
  "attribution_timestamp": "2026-10-09T09:01:13",
  "attribution_method": "ip_device_match"
}
```

Otherwise: `{"attributed": false, "message": "User has no attribution (organic user)"}`.

## GET /sdk/recent-conversions

`/sdk/recent-conversions?app_user_id=user_123&limit=10` — the user's latest purchase events in this app, newest first, so a test build can confirm a purchase reached InfluTo. `limit` is 1–50 (default 10). No amounts and no creator names.

```json
{
  "app_user_id": "user_123",
  "count": 1,
  "attributed_count": 1,
  "conversions": [{
    "event_type": "INITIAL_PURCHASE", "product_id": "pro_monthly", "store": "APP_STORE",
    "environment": "SANDBOX", "is_test": true, "attributed": true, "referral_code": "MAYA",
    "status": "active", "event_timestamp": "2026-10-09T09:01:13"
  }]
}
```

## Inbound webhooks

InfluTo receives purchase events from RevenueCat; on store-direct apps it checks purchases with Apple and Google itself. It sends no webhooks to your servers. To follow what happens, use **Real-Time Events** in the dashboard or the [agent API](#agent-rest-api).

### RevenueCat

`POST https://influ.to/api/webhooks/revenuecat/{app_id}` — **Setup & SDK** shows the full URL with your app's ID. Set it up as described in [RevenueCat](https://docs.influ.to/integrations/revenuecat.md).

- **Auth:** RevenueCat's "Authorization header value" must be `Bearer rc_webhook_…`, the secret InfluTo generates under **Setup & SDK → Webhook** (shown once; regenerate it there or in **Settings → Integration**). The bare token, a lowercase `bearer` and stray whitespace are accepted too. Rejected calls are counted and shown on the Setup page.
- **Body:** RevenueCat's standard webhook JSON. InfluTo reads the code from the subscriber attribute `influto_code`. `influto_referral` is for your own RevenueCat targeting; InfluTo doesn't read it. Without a code, it looks for an attributed click with the event's app user ID — see [`/sdk/identify`](#post-sdkidentify). A user who already converted for a creator stays with that creator, whatever code arrives later.
- **Environments:** send both. `SANDBOX`, `XCODE` and `LOCAL_TESTING` events go through attribution but never reserve money or count in stats.

| Event | What InfluTo does |
|---|---|
| `TEST` | Marks the webhook as connected |
| `INITIAL_PURCHASE` | Creates the conversion when the user is attributed; a paid purchase earns commission, a trial waits until it converts |
| `RENEWAL` | Commission for each paid renewal |
| `NON_RENEWING_PURCHASE` | Commission for each one-time purchase |
| `CANCELLATION`, `UNCANCELLATION`, `EXPIRATION` | Updates the subscription's state |
| `PRODUCT_CHANGE` | Updates the product; the next renewal's price sets the commission |
| `BILLING_ISSUE` | Logged |
| `REFUND` | Reverses the commission |

Promotional grants (store `PROMOTIONAL`, including the ones InfluTo makes for free-access codes) are acknowledged and ignored, as are event types not in the table.

| Response | When |
|---|---|
| `200` `{"received": true, "event_id": "…"}` | Accepted and processed |
| `200` `{"received": true, "error": "…", "event_id": "…"}` | Accepted, but processing failed. Not retried by RevenueCat or by InfluTo — the error is in the response body in RevenueCat's delivery log. |
| `400` | The body isn't JSON |
| `401` | Missing or wrong Authorization value; the body says how to fix it |
| `404` | No app with this ID |

Events are idempotent on app, event type, transaction ID and event timestamp, so a redelivered event is recorded once.

## Agent REST API

The API that AI agents and scripts use to run your program — apps, campaigns, creators, analytics, integration status — lives under `https://influ.to/api/agent/*`. It uses an agent key (`it_mcp_…`, from **Connect AI Agent**) or an OAuth token, never the SDK key. The MCP tools that read or change your account are wrappers over these endpoints.

- Endpoints, scopes and errors: [MCP tools, scopes and REST API](https://docs.influ.to/agents/tools.md#rest-endpoints)
- OpenAPI spec: [https://influ.to/api/agent/openapi.json](https://influ.to/api/agent/openapi.json)
- Status codes: [Limits and errors](https://docs.influ.to/reference/limits-and-errors.md#agent-api-and-mcp)

---

<!-- https://docs.influ.to/reference/limits-and-errors -->
# Limits and errors

> Rate limits, request size, SDK error types and codes, HTTP status codes for the SDK API, webhooks and the agent API, and the rules for codes and app slugs.

This page collects every limit and error you can run into: how fast you can call InfluTo, what each SDK throws, what each status code means, and the format rules for codes and app slugs. For the endpoints themselves, see the [HTTP API](https://docs.influ.to/reference/http-api.md); for the methods, the [SDK reference](https://docs.influ.to/reference/sdk.md).

## Rate limits

| What | Limit | Over the limit |
|---|---|---|
| SDK API (`/api/sdk/*`) and referral links | Per IP address, set well above what a real app or campaign produces — including many users behind one mobile-carrier address | `429` |
| MCP tool calls | 240 per minute per connected account | The tool call fails with an error that starts with `429` |
| MCP sign-in and client registration | Per IP address | `429` |

- If you get a `429`, back off and retry; a script calling in a tight loop is the usual cause.
- `identify` is de-duplicated on the server: the same SDK key and user ID within 60 seconds is answered without doing the work again (`"deduplicated": true`). Call it once per launch, never from a render loop.
- The RevenueCat webhook and the agent REST API have no per-request limit; the agent API has [invite limits](#agent-api-and-mcp) instead.

## Request size

- Every request body is limited to **20 MB**; larger requests get `413`.
- Asset uploads in the dashboard (**Assets**) are limited to 20 MB per file.

## What throws and what fails soft

Only `initialize` and `reportPurchase` throw on network and server errors. The rest return a safe value, so a slow or failed request never crashes your app.

| Method | On failure |
|---|---|
| `initialize` | Throws |
| `reportPurchase` | Throws |
| `checkAttribution` | `{ attributed: false, message: "Error checking attribution" }`, not stored, retried next launch. Throws when called before `initialize` succeeded (iOS returns `attributed: false` instead). |
| `identifyUser`, `trackEvent` | Nothing (logged when `debug` is on) |
| `getActiveCampaigns` | `[]` |
| `validateCode` | `{ valid: false, error_code: "NETWORK_ERROR" }` |
| `setReferralCode` | `{ success: false, message: … }` |
| `applyCode` | The validation result with `applied: false` |
| `checkAccess` | `{ hasAccess: false }` |
| Automatic capture | Failed reports are counted in `failed` and retried on a later back-sync. React Native's `enableAutoPurchaseCapture` and `syncExistingPurchases` throw when called before `initialize`. |

## SDK error types

| Platform | Thrown type | What it carries |
|---|---|---|
| React Native | `Error` | Message `API request failed: <status> - <body>`, or `InfluTo SDK not initialized. Call InfluTo.initialize() first.` |
| iOS | `InfluToError` | `.notInitialized`; `.notConfigured(String)` for any `400`; `.retryable(status:)` for any `5xx`, including `503`; `.http(status:body:)` for other statuses; `.decoding(Error)`; `.transport(Error)` |
| Android | `InfluToError` (sealed, an `Exception`) | `NotInitialized`; `Server(status, body)` with `retryable` (status 500 or higher) and `notConfigured` (status 400); `Transport(cause)`; `Decoding(cause)` |
| Flutter | `InfluToException` | `statusCode`, `body`, `message`; `retryable` (500 or higher), `notConfigured` (400). Network failures have no `statusCode`. |
| Web | `InfluToApiError` | `status`, `body`, `message` for any non-2xx answer. Other failures — not initialized, no `apiKey`, `reportPurchase` without `platform` in a browser — throw a plain `Error`. |

`notConfigured` covers every `400` from `/sdk/purchase`: the platform isn't switched to store-direct yet, or the proof is missing or failed verification. A `503` means the exchange rate wasn't available; retry later.

<!-- tabs -->
```ts title="React Native / Expo"
try {
  await InfluTo.reportPurchase({ platform: 'android', purchaseToken });
} catch (e) {
  if (String(e).includes('failed: 503')) scheduleRetry();
}
```
```swift title="iOS (Swift)"
do {
    _ = try await InfluTo.reportPurchase(jws: jws)
} catch InfluToError.retryable(let status) {
    scheduleRetry(after: status)
} catch {
    print("InfluTo:", error)
}
```
```kotlin title="Android (Kotlin)"
try {
    InfluTo.reportPurchase(purchaseToken = purchase.purchaseToken)
} catch (e: InfluToError.Server) {
    if (e.retryable) scheduleRetry()
}
```
```dart title="Flutter (Dart)"
try {
  await InfluTo.instance.reportPurchase(platform: 'android', purchaseToken: token);
} on InfluToException catch (e) {
  if (e.retryable) scheduleRetry();
}
```
```ts title="Web / Capacitor / PWA"
import InfluTo, { InfluToApiError } from '@influto/web';

try {
  await InfluTo.reportPurchase({ platform: 'android', purchaseToken });
} catch (e) {
  if (e instanceof InfluToApiError && e.status === 503) scheduleRetry();
}
```
<!-- /tabs -->

## Code validation errors

`validateCode` and `applyCode` return these in `error_code` (React Native, web) or `errorCode` (iOS, Flutter as a string; Android as the `CodeErrorCode` enum, which adds `UNKNOWN`).

| Code | When | Server text in `error` |
|---|---|---|
| `INVALID_FORMAT` | Fewer than 4 or more than 20 characters after cleanup | `Code must be 4-20 characters` |
| `CODE_NOT_FOUND` | No active creator code in an active campaign, and no free-access code, matches | `Code not found or inactive` |
| `CODE_EXPIRED` | A free-access code that expired or has no seats left | `Code expired or usage limit reached` |
| `NETWORK_ERROR` | Set by the SDK: the request failed, or the SDK isn't initialized | `Network error or invalid response` or `SDK not initialized` |

`/sdk/set-referral-code` can also answer `MISSING_USER_ID` for a free-access code sent without a user ID. The SDKs' `SetCodeResult` doesn't expose the code; you get `success: false` and the message "Could not identify your account. Please try again."

## HTTP status codes for /api/sdk/*

| Status | Meaning | Endpoints |
|---|---|---|
| `200` | Success. "Not attributed", "invalid code" and "duplicate" are all `200` answers — read the body. | All |
| `400` | Empty `app_user_id`; or, on `/sdk/purchase`, the platform isn't store-direct, credentials are missing, the proof is missing or failed verification, or the platform isn't `ios`/`android` | `identify`, `access`, `recent-conversions`, `purchase` |
| `401` | Missing, malformed, unknown or deactivated SDK key | All |
| `404` | Unknown or inactive code | `set-referral-code` |
| `409` | Android one-time purchase not in the PURCHASED state | `purchase` |
| `413` | Body larger than 20 MB | All |
| `422` | A required field or query parameter is missing or has the wrong type | All |
| `429` | Rate limit | All |
| `500` | Unexpected server error | All |
| `503` | Exchange rate unavailable — retry later | `purchase` |

The store-direct `400` is intentional: until you [switch the platform to store-direct](https://docs.influ.to/integrations/store-direct.md), and that switch needs a green credential check, the endpoint rejects reports. So it's safe to ship the SDK first.

## RevenueCat webhook responses

| Status | Meaning |
|---|---|
| `200` | Accepted. If processing failed, the body also has `"error"`; the event isn't retried by RevenueCat or by InfluTo. |
| `400` | The body isn't valid JSON |
| `401` | Missing or wrong Authorization value. The body says how to fix it, and the Setup page shows a warning. |
| `404` | No app with the ID in the URL |

A low wallet balance is not a webhook error: the conversion is still recorded. See [RevenueCat](https://docs.influ.to/integrations/revenuecat.md) and [inbound webhooks](https://docs.influ.to/reference/http-api.md#inbound-webhooks).

## Agent API and MCP

The agent REST API (`/api/agent/*`) and the MCP tools answer with these statuses; an MCP tool error's text starts with the status.

| Status | Meaning |
|---|---|
| `400` | Invalid input, for example a batch of more than 500 invites |
| `401` | Missing, invalid, expired or revoked agent key or token |
| `402` | Not enough unreserved wallet balance: activating a campaign and sending email invites need at least $50; marketplace invites need $20 per open invite |
| `403` | The key or token lacks the scope, or the action is closed to agents (money, payouts, credentials, admin) |
| `404` | Not found — also returned for anything outside the organizations you granted, so nothing leaks |
| `429` | More than 240 MCP tool calls in a minute, or an invite limit: 100 email invites per organization per 24 hours, or one open marketplace invite per $20 of unreserved balance |

Details: [MCP tools, scopes and REST API](https://docs.influ.to/agents/tools.md#limits-and-errors).

## Code format

**Creator referral codes** (the code in `influ.to/{app_slug}/{CODE}`):

- 4–20 characters: `A–Z`, `0–9`, `_` and `-`. Stored uppercase.
- Not one of `ADMIN`, `TEST`, `API`, `SYSTEM`, `NULL`, `ROOT`, `DELETE`, `REMOVE`.
- Can't start with `INFLU-`, which is reserved for creator access codes InfluTo issues itself.

**Free-access codes** you create on **Free Access Codes**: the same characters and length, uppercase, unique across InfluTo, and also never starting with `INFLU-`.

**When a user types a code**, the SDK trims and uppercases it. The server then ignores spaces and any other character outside the alphabet when it looks the code up, and checks creator codes before free-access codes. The SDK stores and sends to RevenueCat the code it was given, so clean the input in your field — see [building your own field](https://docs.influ.to/reference/ui.md#build-your-own-field).

## App slug

The slug is the first part of your referral links, `influ.to/{app_slug}/{CODE}`.

- 3–20 characters: lowercase letters, digits and `-` (the dashboard enforces this as you type).
- Unique across InfluTo, and not one of the names the site itself uses (such as `api`, `dashboard` or a language code). **My Apps → Add App** checks availability as you type.

---

<!-- https://docs.influ.to/advanced/attribution -->
# How attribution works

> How InfluTo connects an install and its purchases to the creator who referred the user — typed codes and links first, link-click matching as the fallback.

InfluTo is **deterministic first**: whenever the referral code or link reaches the app directly, the match is exact. A link-click fallback covers taps that never carried a code into the app. Every attributed purchase is verified with the store (through RevenueCat, StoreKit 2 or Google Play) before a commission exists.

InfluTo never uses the IDFA or any advertising identifier, never asks for App Tracking Transparency permission, never matches by device characteristics, and never links a user across apps or websites. What to declare in the stores: [Privacy & App Store review](https://docs.influ.to/advanced/privacy.md).

## Referral code entry (exact)

1. The user hears or reads a creator's code — a podcast, a video description, a caption, in person.
2. They install the app and type the code into your code field (the ready-made component, or your own field calling `applyCode()`).
3. The SDK validates the code with InfluTo and records the attribution.
4. On RevenueCat apps, the SDK also writes the `influto_code` subscriber attribute.

A typed code is an explicit action by the user. It attributes on every platform and needs no permission of any kind. Manual code entry is on by default for new apps (**Settings → Advanced**). How to design the field: [Let users enter a referral code](https://docs.influ.to/guides/referral-codes.md).

## Links that carry the code into the app (exact)

- **Web, Capacitor, Cordova and PWA apps:** the referral link opens your web app with the code as a URL parameter; `@influto/web` reads it and claims that exact click.
- **Android apps built with the web SDK:** links to Google Play also carry the code in the Play-signed Install Referrer, which `@influto/web` accepts through `captureInstallReferrer()`.
- **RevenueCat:** if your app already knows the code — your own deep link or promo flow — setting the `influto_code` attribute attributes the customer directly.

## Link-click matching (fallback)

When someone taps a creator's link, goes to the App Store or Google Play and installs without the code reaching the app, InfluTo matches that install to the recent tap on the same link, within 72 hours. It's a best-effort match limited to that app and that window:

- Device characteristics such as model, screen size or timezone are never compared — it is not device fingerprinting.
- Nothing is matched across other apps, websites or ad networks.
- The match only ever decides between "referred by this creator" and "organic".
- A typed code or an in-app code always overrides it.

If a tap can't be matched, the install counts as organic. Nobody is charged for an unattributed install; commissions only exist once a real purchase is verified.

## Attribution window

Link-click matching looks back 72 hours from the install. The window is the same for every app.

It applies to link-click matching only. Typed codes and in-app links aren't limited by it.

## Lifetime attribution

Once a user's purchase is attributed to a creator, every later purchase and renewal by that user stays with that creator. A code typed later doesn't move an existing subscriber to someone else. Plan changes follow the new price on the next renewal.

## Which method wins

| Method | Match | Typical use | What the user does |
|---|---|---|---|
| Referral code entry | Exact | Podcasts, video, captions, word of mouth | Types the code |
| Link with in-app hand-off (web SDK: URL parameter or Play Install Referrer) | Exact | Link in bio, stories, web apps | Taps the link |
| RevenueCat attribute set by your app | Exact | Your own deep links or promo flows | Nothing |
| Link-click matching | Best effort, within the window | Store links where the code can't travel | Taps the link |

- Several taps: the most recent one wins.
- A tap and a typed code: the typed code wins — until the user's first attributed purchase, after which lifetime attribution applies.

## Privacy and compliance

- No IDFA, no advertising ID, no ATT prompt, no cross-app tracking.
- No device fingerprinting: attribution never matches by device characteristics.
- The iOS SDK ships an Apple privacy manifest declaring no tracking.
- Users can ask for their attribution data to be deleted; retention follows the [Privacy Policy](https://influ.to/privacy).

## Click quality

Clicks are screened for bots, link previews and automated or repeated tapping before they count, and flagged clicks are left out of creator stats and milestone progress. Commissions only come from purchases the store has verified. See [Analytics](https://docs.influ.to/platform/analytics.md) for how clicks are counted.

---

<!-- https://docs.influ.to/advanced/privacy -->
# Privacy and App Store review

> What the InfluTo SDKs collect and never touch, and exactly what to declare in App Store Connect's privacy label and Google Play's Data safety form.

This page lists what the InfluTo SDKs send, what they never access, and the answers to give in App Store Connect and the Google Play Console.

## The short version

- **No IDFA, no Advertising ID, no ANDROID_ID.** The SDKs never read an advertising or system identifier.
- **No App Tracking Transparency prompt.** InfluTo does not track users across apps or websites, so ATT does not apply and must not be requested for InfluTo.
- **No device fingerprinting.** Attribution never matches by device characteristics, and nothing is shared with ad networks or data brokers.
- **First-party, per app.** Attribution links an install and its purchases to a referral code or link click for that app only.
- **Deterministic first.** Typed referral codes, in-app link parameters, the Play Install Referrer (web SDK) and the RevenueCat `influto_code` attribute attribute exactly; link-click matching is a window-limited fallback. See [How attribution works](https://docs.influ.to/advanced/attribution.md).

## What the SDK sends

All requests go to `https://influ.to/api` over TLS, authenticated with the app's SDK key.

| When | Data | Purpose |
|---|---|---|
| Initialize / first launch | SDK name and version, app version, platform, device brand and model, OS version, screen size, timezone, language, a random per-install ID generated by the SDK | Attribute the install to a referral code or link click; show SDK health on the Setup page |
| Code validation / application | The referral or access code the user entered, plus the fields above | Validate the code and record the attribution |
| Identify (optional) | Your app's user ID (for example the RevenueCat app user ID) | Match store and RevenueCat purchase events to the attributed install |
| Purchase report (store-direct only) | Store transaction proof (StoreKit 2 signed transaction or Google Play purchase token), product ID | Verify the purchase with Apple or Google before any commission exists |
| Custom events (optional) | Event name and the properties you pass | Funnel analytics on the dashboard |

InfluTo's servers also see the request's IP address, used to derive the country and to screen clicks and installs for fraud. The SDKs never access contacts, precise location, photos, the clipboard or other apps.

## Apple: privacy manifest and App Privacy label

The iOS SDK ships a `PrivacyInfo.xcprivacy` manifest with `NSPrivacyTracking = false`, no tracking domains, and these collected data types — all declared *not linked to the user* and *not used for tracking*:

- Device ID (the SDK's random per-install ID) — App Functionality
- Product Interaction (only with `trackEvent`) — Analytics
- Purchase History (only with `reportPurchase`) — App Functionality

Required-reason APIs used: **UserDefaults**, reason `CA92.1` (the SDK stores its own attribution state). No other required-reason API is used.

App Store Connect answers for the InfluTo part of an app:

| Data type | Collected | Linked to user | Used for tracking | Purpose |
|---|---|---|---|---|
| Identifiers → Device ID | Yes | No | No | App Functionality |
| Purchases → Purchase History | Only with `reportPurchase` | No | No | App Functionality |
| Usage Data → Product Interaction | Only with `trackEvent` | No | No | Analytics |

If your app passes its own user ID to `identifyUser`, declare "Linked to user" according to how that ID is treated elsewhere in your app. Don't enable ATT or `NSPrivacyTracking` for InfluTo, and don't forward InfluTo data to an ad network.

## Google Play: Data safety form

The core Android SDK (`to.influ:android-sdk`) declares only the `INTERNET` permission and doesn't request `AD_ID`. The optional `android-sdk-billing` artifact adds `com.android.vending.BILLING` for purchase capture.

| Data type | Collected | Shared | Purpose |
|---|---|---|---|
| Device or other IDs (SDK install ID; brand, model, OS version, screen size, timezone, language) | Yes | Yes (InfluTo, as processor) | App functionality, Analytics |
| App activity → Other actions (referral code, custom events) | With `trackEvent` / `identifyUser` | Yes | App functionality, Analytics |
| Financial info → Purchase history | With `reportPurchase` | Yes | App functionality |
| App info and performance (app and SDK version) | Yes | Yes | Analytics |

Advertising ID: **No**. Encrypted in transit: **Yes**. Users can request deletion: **Yes**.

## A privacy policy paragraph for your app

> This app uses InfluTo (influ.to) to attribute installs and purchases to referral and affiliate campaigns. It transmits non-advertising device information (brand, model, OS version, screen size, timezone, language), a random install identifier and, where you enter one, the referral code you used. InfluTo does not use advertising identifiers and does not track you across other apps or websites. You can request deletion of this data by contacting us or InfluTo at hello@influ.to.

## Deletion and retention

- `clearAttribution()` removes the SDK's local state on the device.
- Server-side deletion of a user's attribution data is done on request — yours or the user's — at hello@influ.to. There is no self-service deletion API.
- Records of attributed purchases and payouts are kept for 7 years as financial records; everything else follows the [Privacy Policy](https://influ.to/privacy).
- Processing terms: [Terms of Service](https://influ.to/terms) and the Privacy Policy; a data processing agreement is available on request.

## Consent in the EU

Attributing a referral the user was part of is processed on the basis of legitimate interest (paying the creator who referred them) and involves no profiling or advertising. Apps that gate all non-essential SDKs behind a consent screen can call `checkAttribution()` after consent, or lead with typed code entry, which works without any matching.

---

<!-- https://docs.influ.to/advanced/troubleshooting -->
# Troubleshooting

> Fixes for the common InfluTo problems — the SDK not connecting, installs counted as organic, codes rejected, purchases not attributed, campaigns that won't activate and payouts that didn't arrive.

Find your symptom below. Most problems show up first in the dashboard: **Setup & SDK** shows whether the SDK has connected and whether RevenueCat calls were rejected, and **Real-Time Events** shows every SDK event and purchase as it arrives. With an AI agent connected, `influto_integration_status` lists what's still missing.

## The SDK doesn't connect

**`initialize` throws.** It's one of only two calls that throw. A `401` means the API key is wrong — copy it again from **Setup & SDK** (it starts with `it_`; agent keys starting with `it_mcp_` don't work in the SDK). Other errors are usually network problems on the device.

**Setup & SDK never shows a connection.** `initialize` isn't running. On Android, `initialize` is a suspend function — call it inside a coroutine or use the callback overload, otherwise it doesn't compile or never runs. On web apps built with Cordova, the default Content Security Policy blocks requests to `https://influ.to` — allow it.

## Installs show as organic

- **The tap and the first launch happened on different networks**, or more than 72 hours apart. Link-click matching only connects an install to a tap from the last 72 hours on the same network. A typed code always works.
- **The campaign isn't active.** Codes and links only attribute for active campaigns.
- **`checkAttribution` isn't called at launch**, or is called before `initialize` finished.
- **You're re-testing on the same device.** The result is stored once per install; call `clearAttribution()` or reinstall.

## A code is rejected

| Error | Meaning |
|---|---|
| `INVALID_FORMAT` | Not 4–20 characters of letters, digits, `_` or `-` |
| `CODE_NOT_FOUND` | No active creator has this code for this app — check the spelling and that the creator's campaign is active |
| `CODE_EXPIRED` | A free-access code past its expiry date |
| `NETWORK_ERROR` | The device couldn't reach InfluTo |

Codes are trimmed and uppercased before they're checked, so case and stray spaces don't matter. Free-access codes (`INFLU-…`) need manual code entry turned on in **Settings → Advanced**.

## RevenueCat purchases don't arrive

- **Setup & SDK says RevenueCat is sending a wrong Authorization value.** Generate the secret again and paste it into RevenueCat's *Authorization header value* field exactly as shown, including `Bearer`. Or connect automatically with a v2 secret key.
- **Nothing arrives at all.** Check the webhook URL contains this app's ID, the environment is "Both Production and Sandbox", and the events filter is "All events". RevenueCat's **Send Test Event** should appear in Real-Time Events within seconds.

## Purchases arrive but aren't attributed

- **The subscriber has no `influto_code` attribute.** On iOS, Flutter and web, the SDK can only write it if you pass the RevenueCat setter, hook or binding. On React Native, `react-native-purchases` must be configured before `checkAttribution` or `applyCode` runs.
- **`identifyUser` isn't called.** It's InfluTo's fallback for events without the attribute.
- **The user was already attributed to another creator.** The first creator to bring a paying user keeps them.
- **It was a free trial.** Trials are recorded but only earn once they convert to paid.

## Store-direct problems

| Symptom | Fix |
|---|---|
| `reportPurchase` answers `400` | The credentials aren't green yet, or the platform isn't switched to store-direct in **Settings → Validation** |
| TestFlight purchases fail verification | The Apple environment is set to Production — use Sandbox while testing |
| Google validation stuck on "propagating" | New Play Console permissions take up to 48 hours to reach the API |
| `409` on Android | The one-time purchase is still pending; report it once it's PURCHASED |
| `503` | The exchange rate wasn't available — retry; reports are idempotent |
| Nothing is captured automatically | The platform's capture code is missing (`expo-iap`/`react-native-iap`, `android-sdk-billing`, `influto_iap` with `enable()`, or a web `purchaseSource`), or `autoCapture` is false |
| Android one-time purchases fail | Add their product IDs to `oneTimeProductIds`, or pass `productId` to `reportPurchase` |

## Campaigns and money

- **A campaign won't activate.** Activation needs at least $50 available in the wallet (balance minus what's already reserved). Add funds under **Billing**.
- **A campaign paused itself.** The wallet ran too low. Conversions still count for 72 hours after the pause and referral links keep working; add funds and resume the campaign.
- **A creator wasn't paid.** Payouts run on the 1st for the previous month and need at least $20, a completed Stripe Connect account, and a country InfluTo can pay (33: the US, Canada, the UK, Switzerland, Norway, Liechtenstein and the EU). Smaller balances roll over. Failed payouts are retried daily.
- **A commission disappeared.** The purchase was refunded; refunds reverse the commission, and if it was already paid it's deducted from the creator's next payout.

## Still stuck?

Email [hello@influ.to](mailto:hello@influ.to) with your app slug, the platform, the SDK version and what you see in Real-Time Events. If you use an AI agent, include the output of `influto_doctor`.

---

<!-- https://docs.influ.to/advanced/faqs -->
# Frequently asked questions

> Short answers about InfluTo for developers — pricing, which SDK to use, RevenueCat or not, attribution, creators, payouts, refunds and privacy.

Short answers, with links to the page that has the details.

## Pricing and money

### What does InfluTo cost?

$0 a month. For each verified purchase a creator brings, you pay their commission plus a 10% InfluTo fee on the same price — for a $9.99 subscription at 30%, that's $3.00 for the creator and $1.00 for InfluTo. Conversions with a $0 commission carry no fee. Larger programs can agree volume pricing in writing. See [Commissions and fees](https://docs.influ.to/platform/commissions.md).

### Why do I need a prepaid wallet?

So creators are always paid. Each conversion reserves its commission and fee from your wallet, and campaigns need at least $50 available to go live. Deposits start at $50, unused balance can be withdrawn, and a wallet that was never used is refunded automatically after 30 days. See [Wallet and payouts](https://docs.influ.to/platform/wallet.md).

### When and how are creators paid?

On the 1st of each month, for the previous month, through Stripe Connect, once a creator has at least $20. Smaller balances roll over. Creators can be paid in 33 countries: the US, Canada, the UK, Switzerland, Norway, Liechtenstein and the 27 EU countries.

### What happens with refunds?

The commission is reversed. If the creator was already paid, it's deducted from their next payout. Subscription refunds on both stores and Google Play one-time refunds are detected automatically.

### Can I change the commission later?

Yes. Increases apply immediately. Decreases take effect after 7 days' notice, and creators are emailed. Users a creator already brought keep the rate they were acquired at for renewals and refunds.

## Integration

### Which SDK do I use?

The one for your app's language: React Native (also Expo), iOS (Swift), Android (Kotlin), Flutter, or web for Capacitor, Ionic, Cordova and PWAs. See [Choose an SDK](https://docs.influ.to/sdk.md).

### Do I need RevenueCat?

No. Every SDK works with RevenueCat or without it ("store-direct", where InfluTo checks purchases with Apple and Google directly). Use exactly one per platform. See [Choose a path](https://docs.influ.to/integrations.md).

### How long does the integration take?

Plan for an afternoon. The code is a few calls; most of the time goes into store or RevenueCat settings and a sandbox test. An AI agent connected over [MCP](https://docs.influ.to/agents/index.md) can do most of it.

### Does it work with Expo?

Yes, with the React Native SDK. For store-direct purchase capture you need `expo-iap` or `react-native-iap`, which require a development build rather than Expo Go.

### Is there a test mode?

You don't need one. The same API key works in sandbox and production; sandbox and TestFlight purchases show up in Real-Time Events but never move money or change stats. See [Verify the integration](https://docs.influ.to/integrations/testing.md).

### Does InfluTo send webhooks to my server?

No. InfluTo receives events (from RevenueCat and the stores) but doesn't send outbound webhooks. Use the dashboard, the [agent API](https://docs.influ.to/agents/tools.md) or MCP tools to read events and analytics.

## Attribution

### How does InfluTo know who referred a user?

A typed code or a link that carries the code into the app is an exact match. Otherwise link-click matching connects the install to a recent tap on the creator's link, within 72 hours. See [How attribution works](https://docs.influ.to/advanced/attribution.md).

### How long is the attribution window?

72 hours, the same for every app. It only applies to link-click matching — typed codes aren't limited by it.

### Does a creator keep a subscriber forever?

Yes — the first creator who brings a paying user earns on that user's renewals for as long as they stay subscribed, unless the campaign sets a commission period (for example 12 months) or its budget runs out. See [Limits](https://docs.influ.to/platform/commissions.md#limits-commission-period-conversion-cap-and-budget).

### Do I need the ATT prompt?

No. InfluTo doesn't use the IDFA or track users across apps. See [Privacy & App Store review](https://docs.influ.to/advanced/privacy.md).

## Creators

### Where do creators come from?

Your own audience and partners, whom you invite with a join link or by email, and creators browsing [influ.to/affiliate-programs](https://influ.to/affiliate-programs), where public programs are listed. See [Invite creators](https://docs.influ.to/platform/invite-influencers.md).

### Do creators pay anything?

No. Joining is free and there are no fees on their side.

### Can one creator get a different rate?

Yes — set a **custom commission** when you invite them (dashboard invite form, or `influto_invite_creator` for an [AI agent](https://docs.influ.to/agents/index.md)).

## Account

### Can my team share one account?

Not yet — team member invites aren't available. One organization owns the apps and the wallet, and it's managed from one login.

### How do I delete an app?

In **Settings → Advanced**. Deletion is blocked while the app has draft, active or paused campaigns, and the data is kept for financial records.

---

# InfluTo for AI agents — connect, tools, REST

> InfluTo is a referral & affiliate ATTRIBUTION platform for mobile apps (iOS, Android,
> React Native, Flutter, web/Capacitor). A developer creates an app + campaign at https://influ.to,
> drops in one of five SDKs, initializes with an API key, and InfluTo attributes installs and
> validates in-app purchases to influencer referral codes — via either RevenueCat (webhook)
> or store-direct (Apple App Store Server API / Google Play service account).
> This page is the control-plane reference: how an AI agent connects to InfluTo, what it may do
> (scopes), every MCP tool, and the /api/agent/* REST surface behind them.

## Connect (OAuth 2.1 — one command, no keys)

The InfluTo MCP server lives at **https://influ.to/mcp** (Streamable HTTP).

- **Claude Code:** `claude mcp add --transport http influto https://influ.to/mcp`
- **claude.ai (web / desktop):** Settings → Connectors → Add custom connector → https://influ.to/mcp
- **Codex CLI:** `codex mcp add influto --url https://influ.to/mcp`
- **VS Code (Copilot agent mode):** `code --add-mcp '{"name":"influto","type":"http","url":"https://influ.to/mcp"}'`
- **Gemini CLI:** `gemini mcp add --transport http -s user influto https://influ.to/mcp`
- **ChatGPT (web):** chatgpt.com/plugins → + → Add custom MCP server → URL https://influ.to/mcp, authentication OAuth → Create as a plugin (Business / Enterprise / Edu; Pro is read-only)
- **Cursor / any MCP client:** add `https://influ.to/mcp` as an HTTP (streamable) MCP server — Settings → MCP → Add server → { "influto": { "url": "https://influ.to/mcp" } }

On the agent's first InfluTo call your browser opens an InfluTo consent page —
sign in (or sign up), pick the organization the agent may act on, untick any scope you do not want, click
Approve. Done: the client stores the OAuth grant and refreshes it automatically. Revoke any
time at https://influ.to/dashboard/connect-agent (Connected agents).

Headless / CI fallback: mint an `it_mcp_*` agent key at
https://influ.to/dashboard/connect-agent (shown once) and send it as
`Authorization: Bearer $INFLUTO_API_KEY` — same MCP URL, same REST surface, same scopes.

## Auth model

- **OAuth 2.1 (primary):** discovery + dynamic client registration + PKCE browser consent with an
  organization picker. Access tokens live ≤1h and refresh automatically; revoking the grant on the
  dashboard kills refresh immediately (the current token dies within the hour).
- **Agent keys `it_mcp_*` (CI fallback):** minted on https://influ.to/dashboard/connect-agent,
  shown once, revocable, same scopes.
- Both principals hit the same org-scoped guards: a missing scope is a **403**, a cross-tenant id
  is a **404** (never a 403 — no existence oracle).
- The dashboard's own REST (`/api/apps/*`, `/api/campaigns/*` — no `/agent/`) is
  session-JWT only. **An API key there gets 401 by design** — agents always use `/api/agent/*`.

## Scopes

| Scope | Grants |
|---|---|
| `apps:read` | List and inspect your apps and their integration status |
| `apps:write` | Create and update apps (names, links, creator-code settings) |
| `campaigns:read` | View campaigns, milestones and settings |
| `campaigns:write` | Create and update campaigns, bonuses, and their status |
| `analytics:read` | Read clicks, installs, trials, conversions and revenue analytics |
| `creators:read` | List creators, invitations and access codes |
| `creators:write` | Invite creators and create free-access codes |
| `assets:read` | List marketing assets and content examples |
| `assets:write` | Feature/unfeature assets (uploads stay in the dashboard) |
| `billing:read` | See wallet balance and reserved funds (read-only) |
| `integration:verify` | Run integration checks and sandbox test events |

New keys and OAuth consents default to all of the above. Hard-denied to every agent, regardless of grant: money writes
(top-ups, transfers), payouts, raw credentials, deletes, and admin. Secrets and money move only
through dashboard links the HUMAN opens while signed in (top-up, credential upload, asset
upload) — they never transit the agent.

## MCP tools (62)

The live, always-in-sync catalog is the MCP resource `influto://tools` (the server generates it
from its registered tools at read time). Reference bulk lives in resources too:
`influto://contract` (the wire contract) and `influto://sdk/{platform}` (per-SDK reference).

### Discovery (4)

Pure lookups — which SDK, which validation path, which invariant.

- `influto_list_sdks` — The five SDKs (React Native, iOS, Android, Flutter, Web) with package id, registry, repo and current version.
- `influto_recommend_sdk` — Free-text stack ('expo', 'swiftui', 'kotlin', …; platform/hostStack/framework/language/sdkId accepted as aliases) → the ONE SDK + peer deps.
- `influto_recommend_validation` — Pick the ONE validation path: RevenueCat webhook vs store-direct (never both).
- `influto_explain_contract` — Wire-contract invariants per topic: attribution, purchase, comp, dedup, rc-attributes.

### Scaffold (6)

Version-correct code snippets straight from the SDK registry.

- `influto_scaffold_install` — Install command(s) + peer dependencies for an SDK.
- `influto_scaffold_init` — The one-time initialize() snippet (THROWS on failure — surface it).
- `influto_scaffold_attribution` — The checkAttribution() launch snippet.
- `influto_scaffold_manual_code` — Optional manual referral-code entry / ReferralCodeInput snippet.
- `influto_scaffold_report_purchase` — Store-direct purchase-reporting snippet (skip on the RevenueCat path).
- `influto_scaffold_full` — One call → the exact ordered integration steps for a stack + validation path.

### Provision (7)

Stand up the account side: org → app (+ API key) → campaign.

- `influto_whoami` — The developer + organizations behind the connected agent.
- `influto_create_org` — Create an organization (only when whoami shows none).
- `influto_search_store` — Search the App Store + Google Play for an app's store identifiers.
- `influto_scrape_store` — Scrape store metadata incl. the numeric Apple app_store_id.
- `influto_check_slug` — Is an app slug free? (Slugs are globally unique — first segment of referral URLs.)
- `influto_provision` — Org → app (+ API key + webhook secret) → campaign → activate, in one idempotent call.
- `influto_regenerate_webhook_secret` — Rotate the RevenueCat webhook secret (returned once).

### Configure (7)

Wire the purchase-validation path; secrets go through a dashboard link the human opens.

- `influto_get_validation_status` — Per-platform validation config + what's missing (non-secret).
- `influto_setup_revenuecat` — Auto-wires the RevenueCat webhook inside the developer's RC project (autowire=true by default, using the stored v2 secret key); falls back to exact dashboard_steps.
- `influto_get_credential_upload_link` — Dashboard link the HUMAN opens (signed in) to upload credentials — secrets never transit the agent.
- `influto_set_apple_meta` — Non-secret Apple identifiers: Issuer ID, Key ID, environment, App Store ID.
- `influto_validate_store_credentials` — Run the live credential green-check (loop while retryable).
- `influto_activate_store_direct` — Flip a platform to store-direct once the green-check passed.
- `influto_recommend_validation_for_platforms` — Which path to wire and what it needs (configure-flow reminder).

### Verify (4)

The differentiator: prove a real ATTRIBUTED conversion happened.

- `influto_integration_status` — THE verify rollup: {live, checklist[], attributed_conversion_count, campaign health, …}.
- `influto_recent_events` — Recent SDK events + purchase webhooks with attribution flags (SANDBOX/PRODUCTION filter).
- `influto_test_integration` — Fire a SANDBOX INITIAL_PURCHASE through the real attribution pipeline.
- `influto_verify_user_conversions` — Did a specific app_user_id's purchases attribute?

### Operate (17)

Run the program: apps, campaigns (milestone bonuses + i18n), awards, analytics.

- `influto_list_apps` — Every app across the developer's orgs, with canonical click totals.
- `influto_get_app` — Full app detail incl. *_i18n maps, support_email and creator-code settings.
- `influto_update_app` — Update whitelisted app settings (name_i18n / description_i18n / tagline_i18n merge and mark those locales fresh; editing name/description marks translations stale; credentials excluded).
- `influto_list_campaigns` — Campaigns by app/status with canonical clicks + milestone counts.
- `influto_get_campaign` — Full campaign: commission, bonus_rules, i18n copy, stats.
- `influto_create_campaign` — Full-featured create incl. milestone bonus_rules + i18n (created as DRAFT).
- `influto_update_campaign` — Update a campaign — same surface as create (editing name/description marks existing translations stale), incl. enforced limits and tier rules.
- `influto_create_tracking_codes` — Add house tracking codes (per channel / group / account / page / QR) to a tracking campaign: attribution only, no commission, no user benefit.
- `influto_set_creator_commission` — Set one creator's rate after they joined (or reset to the campaign rate): raises apply now, cuts after notice.
- `influto_set_campaign_status` — Activate/pause; activation enforces the prepaid wallet minimum (402 → top-up link).
- `influto_list_bonus_awards` — Milestone awards with creator identity + live fraud-aware progress.
- `influto_review_bonus_award` — Approve or void an earned milestone award (pre-payout only).
- `influto_get_analytics_overview` — Per-app period rollup: canonical clicks (+ decomposition), installs, trials, conversions, revenue, commission.
- `influto_get_campaign_funnel` — Clicks → installs → trials → paid with step rates (find the leak).
- `influto_get_funnel_breakdown` — The funnel per link tag (?s= group, utm_*, referring site): which group or post a code's clicks, installs, trials and paid came from.
- `influto_list_top_affiliates` — Top creators by period revenue for an app or campaign.
- `influto_get_daily_performance` — Zero-filled daily series for trend checks and charts.

### Grow (17)

Recruit and reward creators; read-only wallet visibility; the doctor.

- `influto_list_affiliates` — Every creator in a campaign: codes, canonical clicks, earnings, milestone progress, INFLU- code state.
- `influto_invite_creator` — Invite one creator by email (localized invitation + personal message; optional custom commission).
- `influto_invite_creators_batch` — Bulk-invite from a list/CSV — live capacity accounting, per-item results, partial success.
- `influto_withdraw_invitation` — Withdraw a PENDING invite (frees a marketplace capacity slot).
- `influto_get_join_link` — The shareable public join-page URL (?lang=xx, OG card) + readiness warnings.
- `influto_list_invitations` — Invitation states across campaigns (default: still pending).
- `influto_list_free_codes` — Free-access codes incl. platform-issued INFLU- creator codes + redemption state.
- `influto_create_free_code` — Mint a comp/free-access code (ambassadors, press, VIPs) — no purchase needed; optionally credited to a partner.
- `influto_create_free_codes_bulk` — Mint up to 500 unique codes at once (testers, vouchers, one per group), labelled with a cohort.
- `influto_list_assets` — Marketing assets creators use for content (filter by type/category).
- `influto_set_asset_featured` — Curate which assets show as join-page content examples.
- `influto_get_asset_upload_link` — Dashboard link the HUMAN opens (signed in) to upload asset files.
- `influto_get_wallet` — READ-ONLY wallet snapshot: balance, reserved, safe_available, can_activate_campaigns, and invite_capacity (marketplace slots + daily email budget) — read before inviting.
- `influto_get_wallet_topup_link` — Link to the billing page — the HUMAN, signed in, completes the Stripe checkout.
- `influto_localize_campaign` — Localize campaign copy, stale-aware: refreshes only missing/stale locales unless forced (server translator, or hands the copy back for the agent to translate + write back).
- `influto_localize_app` — Localize app name/description/tagline, stale-aware (server translator, or hands the copy back for the agent to translate + write back via influto_update_app).
- `influto_doctor` — Auth mode, principal, scopes, orgs, per-app freshness — call FIRST when anything misbehaves.

## REST surface (/api/agent/*)

Every MCP tool above proxies one of these endpoints — the REST surface is public and equivalent
(same auth, same scopes, same tenancy). Send `Authorization: Bearer <it_mcp_* key or OAuth token>`.

**Identity & provision**

```
GET  /api/agent/whoami
GET  /api/agent/doctor
POST /api/agent/organizations
GET  /api/agent/store/search · GET /api/agent/store/scrape
GET  /api/agent/apps/check-slug/{slug}
POST /api/agent/provision
POST /api/agent/apps/{app_id}/regenerate-webhook-secret
```

**Configure validation**

```
GET  /api/agent/apps/{app_id}/validation-status
POST /api/agent/apps/{app_id}/credential-setup-link
PATCH /api/agent/apps/{app_id}/apple-meta
POST /api/agent/apps/{app_id}/validate-store-credentials
POST /api/agent/apps/{app_id}/activate-store-direct
```

**Verify (the loop)**

```
GET  /api/agent/apps/{app_id}/integration-status
GET  /api/agent/apps/{app_id}/events/recent
POST /api/agent/apps/{app_id}/test-integration
GET  /api/agent/apps/{app_id}/verify-user-conversions?app_user_id=…
```

**Operate (apps · campaigns · bonuses · analytics)**

```
GET  /api/agent/apps · GET/PATCH /api/agent/apps/{app_id}
GET  /api/agent/campaigns · GET/PATCH /api/agent/campaigns/{campaign_id}
POST /api/agent/apps/{app_id}/campaigns
POST /api/agent/campaigns/{campaign_id}/status
PATCH /api/agent/campaigns/{campaign_id}/affiliates/{affiliate_id}/commission
POST /api/agent/campaigns/{campaign_id}/tracking-codes
GET  /api/agent/bonus-awards · POST /api/agent/bonus-awards/{award_id}/review
GET  /api/agent/apps/{app_id}/analytics/overview
GET  /api/agent/campaigns/{campaign_id}/funnel
GET  /api/agent/apps/{app_id}/analytics/breakdown?group_by=sub1|utm_campaign|…
GET  /api/agent/analytics/top-affiliates
GET  /api/agent/campaigns/{campaign_id}/daily-performance
```

**Grow (creators · codes · assets · wallet)**

```
GET  /api/agent/campaigns/{campaign_id}/affiliates
POST /api/agent/campaigns/{campaign_id}/invite
GET  /api/agent/campaigns/{campaign_id}/join-link
GET  /api/agent/invitations
GET/POST /api/agent/apps/{app_id}/free-codes
POST /api/agent/apps/{app_id}/free-codes/bulk
GET  /api/agent/apps/{app_id}/assets · POST /api/agent/assets/{asset_id}/featured
POST /api/agent/apps/{app_id}/asset-upload-link
GET  /api/agent/wallet · POST /api/agent/wallet/topup-link
POST /api/agent/campaigns/{campaign_id}/localize
POST /api/agent/apps/{app_id}/localize
```

## The VERIFY loop (why integrations trust InfluTo)

1. The SDK in the developer's build fires real `/sdk/init` + `/sdk/track-install`.
2. `influto_integration_status` (or `GET /api/agent/apps/{app_id}/integration-status`) rolls up
   an 8-step checklist: app_created → campaign_active → sdk_initialized → sdk_event_received →
   validation_configured → revenuecat_webhook_wired → purchase_webhook_seen → attributed_conversion.
3. `influto_test_integration` fires a SANDBOX INITIAL_PURCHASE through the REAL pipeline.
4. `influto_recent_events` shows the webhook with `attributed: true` + the referral code.
5. `attributed_conversion_count >= 1` and `live: true` — proof, not vibes. The offline twin is
   the plugin's `scripts/verify_integration.py` (exit 0/1, CI-gateable).

## Troubleshooting

- **Start with `influto_doctor`** — it is deliberately scope-free and reports auth mode
  (oauth | agent_key), principal, granted + hard-denied scopes, organizations, app count and
  per-app SDK-init freshness. A misconfigured connection can still diagnose itself.
- **401 on /api/agent/*** — expired/revoked token or key; reconnect (OAuth) or mint a new key.
- **401 on /api/apps/*** — wrong surface: that is the dashboard-session API. Use /api/agent/*.
- **403** — missing scope (the error names it). **404 on an id you "know" exists** — the id
  belongs to another org; agents only see their granted org.
- **402 on activate/invite** — wallet balance below minimum; call `influto_get_wallet_topup_link`
  and hand the URL to the human, then retry.
- Campaign not attributing? Codes only attribute while the campaign is **active** —
  `influto_get_join_link` also warns when a link is not shareable yet.

## Install as a plugin (Claude Code)

```
/plugin marketplace add influto/influto-plugin
/plugin install influto
```

Two skills ship with it: `influto-integration` (writes the SDK code, works offline) and
`influto-platform` (drives this control plane). First tool call opens the browser consent —
that's the whole onboarding.

---
Machine docs index: [/llms.txt](/llms.txt) · Full corpus: [/llms-full.txt](/llms-full.txt) ·
Wire contract: [/contract.md](/contract.md)