Affiliate

There used to be two separate app types. There is now one. You connect a web payment provider (and give us your site URL), a mobile purchase provider (and give us your App Store / Play Store URLs), or both. Everything else - affiliates, commission rates, products, the referral link, the payout schedule - is shared.

Selling on your website

Selling inside your mobile app

Running both? Do both. They are the same app, so an affiliate who drives a website sale and an app install is one affiliate with one balance.

Referral links come in three formats: a short link (affiliateo.com/r/CODE), a username link, and a direct link on your own domain (yoursite.com?ref=username). Direct links skip the redirect entirely; the tracking SDK captures the ?ref= parameter when the visitor lands.

The minimum percentage rate is 1%. Note that a mobile app billed through Stripe rather than the stores sits in the 90% row: nobody takes a store cut, so the store ceiling does not apply.

The same goes for a purchase made on a website that RevenueCat or Adapty reports (RevenueCat's own Web Billing, or a Stripe or Paddle purchase they track). No store took a cut, so that sale is capped at 90%, not 70%. A store purchase through the same provider stays capped at 70%.

Where the cap is applied

Pick how you take payments

Four ways to wire purchases into your affiliate pipeline. Pick one (or combine Apple + Google for direct native).

RevenueCat, Adapty, the App Store and Google Play connect beside each other, so an app can move from one to another without a gap, and a purchase two of them report is counted once. Connecting one alongside a web provider is what makes the app dual-rail: it does not replace the web side. Selling on the web as well? See how RevenueCat or Adapty work together with Stripe or Paddle.

SDK integration

Install the SDK for each rail you run. A dual app installs both, using the same app ID on either side.

Website

Add the Affiliateo SDK to your website to track affiliate referrals and attribute purchases.

Applies to Stripe, Polar, Paddle, and Whop. Shopify and WooCommerce use their own install paths. see below.

npm install @affiliateo/web

import { AffiliateoProvider } from '@affiliateo/web';

export default function RootLayout({ children }) {
  return (
    <AffiliateoProvider appId="YOUR_APP_ID">
      {children}
    </AffiliateoProvider>
  );
}

'use client'
import { getAttribution } from '@affiliateo/web';

async function handleCheckout() {
  const attribution = getAttribution();
  const res = await fetch('/api/checkout', {
    method: 'POST',
    body: JSON.stringify({ attribution }),
  });
  const { url } = await res.json();
  window.location.href = url;
}

export async function POST(req) {
  const { attribution } = await req.json();

  const session = await stripe.checkout.sessions.create({
    line_items: [...],
    mode: 'payment',
    metadata: attribution,
  });

  return Response.json({ url: session.url });
}

Mobile app

Add the Affiliateo SDK to your mobile app. Choose your platform below.

npm install @affiliateo/react-native @react-native-async-storage/async-storage @react-native-community/netinfo

import { AffiliateoProvider } from '@affiliateo/react-native';

export default function App() {
  return (
    <AffiliateoProvider appId="YOUR_APP_ID">
      <YourApp />
    </AffiliateoProvider>
  );
}

import { useAffiliateoScreen } from '@affiliateo/react-native';

export default function HomeScreen() {
  useAffiliateoScreen('HomeScreen');
  return <YourScreenUI />;
}

There are four values. The first two matter on every provider.

Per provider

export async function POST(req) {
  const { attribution } = await req.json();

  const session = await stripe.checkout.sessions.create({
    line_items: [...],
    mode: 'payment',
    metadata: attribution,
  });

  return Response.json({ url: session.url });
}

// A Payment Link takes no metadata per visitor: it carries one value
// in its address. Send the visitor id; the affiliate is read from it.
const visitorId = localStorage.getItem('affiliateo_visitor_id');
const ref = localStorage.getItem('affiliateo_ref');
const url = new URL('https://buy.stripe.com/YOUR_PAYMENT_LINK');
const reference = visitorId || ref;
if (reference) url.searchParams.set('client_reference_id', reference);
window.location.href = url.toString();

Stripe without Checkout

Some payments never make a Checkout Session: Stripe's PaymentSheet inside an app, the Payment Element on your own page, or a subscription your server starts through the API. Your server creates the PaymentIntent or the Subscription itself, so the values go in that object's own metadata. The code is in the Stripe without Checkout tab above.

Track conversion goals

Goal names must be lowercase letters, digits, underscores, hyphens, or colons on both rails, and optional metadata (a second argument) is bounded to 4KB if you want to slice funnels by property later.

Website

Pageviews auto-track. For specific moments that matter to your funnel (signup_completed, trial_started, initiate_checkout, etc.), you have two options depending on your integration: npm SDK users call track() from a React hook (and trackPageview() for modal or virtual-route pageviews). Script-tag users can additionally drop a data-affiliateo-goal attribute on any button, or data-affiliateo-scroll on a section to fire when it scrolls into view (great for landing pages where you want to know which sections convert).

'use client'
import { useEffect } from 'react'
import { useAffiliateRef } from '@affiliateo/web'

export default function SignupSuccess() {
  const { track } = useAffiliateRef()
  useEffect(() => {
    track('signup_completed', { plan: 'free' })
  }, [])
  return <div>Welcome!</div>
}

'use client'
import { useEffect } from 'react'
import { useAffiliateRef } from '@affiliateo/web'

export default function PricingModal({ open }: { open: boolean }) {
  const { trackPageview } = useAffiliateRef()
  useEffect(() => {
    // Fire a pageview for the modal so it shows up in your funnel
    // even though no real route change happened.
    if (open) trackPageview('/pricing-modal')
  }, [open])
  return null
}

Mobile app

On native SDKs (React Native, Swift, Kotlin, Flutter) screens are tracked when you call page(name) per screen. This is the Mixpanel / Amplitude model. predictable, no ghost events. For specific moments that matter to your funnel (signup_completed, trial_started, feature_used, etc.), call track(). Vanilla / WebView (Capacitor, Ionic, Cordova) loads the m.js script and pageviews on URL change are auto-fired, same as the web SDK.

import { useAffiliateRef } from '@affiliateo/react-native';

function SignupButton({ onNext }) {
  const { track } = useAffiliateRef();
  return (
    <Pressable onPress={() => {
      track('signup_completed');
      onNext();
    }}>
      <Text>Continue</Text>
    </Pressable>
  );
}

Identify signed-in users

Without identify(), the same person browsing on phone and buying on laptop counts as two unrelated visitors and your funnel splits across devices. Call it once after sign-in so Affiliateo can stitch the journey to one person. Idempotent. safe to fire on every page load or app launch. On a dual app this is what ties a website visit and an app install to the same human.

Call logout() from your own sign-out, so whoever uses the phone or browser next is not counted as the person who left. If somebody else signs in on the same device, it simply counts as them from then on. Placeholder ids like "null", "guest" or "0" are ignored.

'use client'
import { useEffect } from 'react'
import { useAffiliateRef } from '@affiliateo/web'
import { useUser } from './your-auth'

export default function AuthBoundary({ children }) {
  const { identify } = useAffiliateRef()
  const user = useUser()
  useEffect(() => {
    if (user) identify(user.id)
  }, [user])
  return <>{children}</>
}

// In your sign-out handler:
// const { logout } = useAffiliateRef()
// await logout()

One customer, two devices

Identify is also what lets a sale follow a customer from one device to another. Someone taps an affiliate's link on their phone and buys on their computer, or the other way round: the buying device never saw the link. Call identify() with the same id on your website and in your app, and a new purchase with no affiliate on its own device is credited to the latest affiliate click the same user made on another device, inside the usual 60 days.

The purchase has to be tied to the user. How depends on where the sale comes from:

Apps on RevenueCat

We give it as a promotional entitlement in your own RevenueCat project, so there is no free access code to add. Just make sure your app sends each person's email to RevenueCat when they sign in: that address is how we find them in your project.

import Purchases from 'react-native-purchases';

// After Purchases.logIn(user.id), for the person who just signed in:
await Purchases.setEmail(user.email);

Apps on the App Store, Google Play, Adapty or Stripe

Apple and Google can't give anyone a subscription from outside your app, so your app asks us. Add two lines from our SDK: pass the email to identify() when someone signs in, then call freeAccess() after sign-in and every time the app opens. Only a scrambled copy (SHA-256) of the email leaves the phone.

const { identify, freeAccess } = useAffiliateRef();

// At sign-in. The email is hashed on the phone; only the hash is sent.
await identify(user.id, { email: user.email });

// After sign-in and on every launch: unlock while it says yes, lock again
// when it says no (the length the owner chose has ended).
const access = await freeAccess();
// access.productId: the plan the owner chose, or null for full access
// access.expiresAt: when it ends, or null for no end
setHasFreeAccess(access.active);

Keep the purchase check you already have and add this one to it: unlock your paid features when the person paid (through StoreKit, Google Play Billing, Adapty or Stripe) or when freeAccess() says active. productId is the plan you picked (null means everything) and expiresAt is when it ends (null means no end). When it says not active, lock them again: that is how an ended length, or you switching it off, reaches the phone.

Free access for every affiliate

One call from your server

{
  "email": "jane@example.com",
  "app_email": "jane@icloud.com"
}

How we find the affiliate in your app

Add a landing page URL in your app settings and affiliates get a fourth link format: yoursite.com?ref=username, with no redirect through affiliateo.com. Put one of these snippets on that page and every arrival with a ref code is recorded, so installs still match back to the right affiliate. Pick one flavor:

<script defer
  data-app="YOUR_APP_ID"
  data-redirect="store"
  data-ios-url="https://apps.apple.com/us/app/your-app/id123456789"
  data-android-url="https://play.google.com/store/apps/details?id=com.yourapp"
  src="https://affiliateo.com/t.js"
></script>

The snippet above runs in the browser, so visitors briefly see your page before the bounce. If you control your server or edge, you can skip that entirely: 302-redirect any request arriving with ?ref= to https://affiliateo.com/r/your-app-slug/{ref} (your app's slug is in its Affiliateo URL). The visitor's browser follows the redirect, so the click is logged with their real IP and device and installs match exactly like short links. Important: do not report the click server-to-server instead, because it would arrive from your server's IP and install matching would break. With this in place you don't need the landing page snippet at all.

export default {
  async fetch(request, env) {
    const url = new URL(request.url)
    const ref = url.searchParams.get('ref')
    if (ref && request.method === 'GET') {
      return Response.redirect(
        `https://affiliateo.com/r/your-app-slug/${encodeURIComponent(ref)}`,
        302,
      )
    }
    return env.ASSETS.fetch(request) // or your existing handler
  },
}

Multi-domain attribution

If your property spans more than one domain (marketing site on marketing.com and your app on app.merchant.com), affiliate ref codes die at every domain boundary because browsers sandbox storage by origin. Without help, an affiliate who sends traffic to your marketing site gets no commission when the visitor signs up on your app domain. Add the other domains via data-allowed-hostnames (script tag) or allowedHostnames (npm SDK prop) and the SDK auto-decorates outbound links with the visitor identity. The receiving domain reads those params on landing, strips them from the URL bar, and the funnel sees one continuous visitor. Both sides need the SDK installed and both need to list the OTHER domains (each side names everyone except itself).

import { AffiliateoProvider } from '@affiliateo/web';

export default function RootLayout({ children }) {
  return (
    <AffiliateoProvider
      appId="YOUR_APP_ID"
      allowedHostnames={['app.merchant.com', 'docs.merchant.com']}
    >
      {children}
    </AffiliateoProvider>
  );
}

Development & debugging

By default the SDK is configured for production safety: localhost is blocked (so npm run dev doesn't pollute your funnel), iframes are blocked (so scrapers and preview tools don't count as pageviews), and debug logs are silent. Turn any of these on with the props or attributes below. Also exposed: a flush() method to force queued events out the door right before a redirect, so they don't get lost when the page navigates away.

import { AffiliateoProvider } from '@affiliateo/web';

export default function RootLayout({ children }) {
  return (
    <AffiliateoProvider
      appId="YOUR_APP_ID"
      // Turn on for end-to-end tests against localhost.
      // Leave false (the default) in production.
      allowLocalhost={process.env.NODE_ENV !== 'production'}
      // Print decision logs to the browser console. Useful when
      // investigating "why aren't my events showing up?".
      debug={process.env.NODE_ENV !== 'production'}
      // Set to true if your site is legitimately embedded inside
      // an iframe (e.g. an embed widget shipped to partners).
      // allowIframe
    >
      {children}
    </AffiliateoProvider>
  );
}

'use client'
import { useAffiliateRef } from '@affiliateo/web'

export default function CheckoutButton() {
  const { track, flush } = useAffiliateRef()
  return (
    <button onClick={async () => {
      track('initiate_checkout', { plan: 'pro' })
      // Force events out NOW before the redirect kills the page.
      // Default flush timer is every 5s, too slow for a redirect.
      await flush()
      window.location.href = '/api/checkout'
    }}>
      Subscribe
    </button>
  )
}

'use client'
import { Purchases } from '@revenuecat/purchases-js';
import { getAttribution } from '@affiliateo/web';

async function handlePurchase(rcPackage) {
  const { affiliateo_ref, affiliateo_visitor_id } = getAttribution();
  await Purchases.getSharedInstance().purchase({
    rcPackage,
    metadata: {
      ...(affiliateo_ref ? { affiliateo_ref } : {}),
      ...(affiliateo_visitor_id ? { affiliateo_visitor_id } : {}),
      // affiliateo_user_id: user.id, // optional: your own id for the buyer
    },
  });
}

A website with no app in a store

If you sell on the web through Stripe or Paddle and send those purchases to RevenueCat or Adapty as well, each sale is reported twice. When the same Stripe or Paddle account is also connected to the app directly, that connection is the record of the money, and the sale is counted once.

This is about purchases made on a website. App Store and Google Play purchases are not affected: two providers that report the same store purchase already count it once.

import { Linking } from 'react-native';
import { useAffiliateRef } from '@affiliateo/react-native';

const { refCode, visitorId } = useAffiliateRef();

async function buy(priceId: string) {
  const res = await fetch('https://api.yourapp.com/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ priceId, refCode, visitorId }),
  });
  const { url } = await res.json();
  await Linking.openURL(url);
}

// POST /checkout: the app sends priceId, refCode and visitorId.
const { priceId, refCode, visitorId } = await req.json();

const session = await stripe.checkout.sessions.create({
  mode: 'subscription', // or 'payment'
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: 'https://yourapp.com/thanks',
  cancel_url: 'https://yourapp.com/pricing',
  // On the session itself (not subscription_data), whatever the mode.
  metadata: {
    affiliateo_app_id: 'YOUR_APP_ID',
    ...(refCode ? { affiliateo_ref: refCode } : {}),
    ...(visitorId ? { affiliateo_visitor_id: visitorId } : {}),
  },
});

return Response.json({ url: session.url });

Renewals need nothing more: each one is credited to the affiliate of the subscription's first payment. A checkout without the code is recorded as organic, unless it is tied to a user you identified who clicked on another device (see One customer, two devices). One Stripe account can sell on your website and in your app at once: both land in the same program, each product at its own rate.

Full endpoint reference →

Website sales

Mobile app sales