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.

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).

One mobile provider per app. Connecting one alongside an existing web provider is what makes the app dual-rail. it does not replace the web side.

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 />;
}

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.

'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}</>
}

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>
  )
}

Full endpoint reference →

Website sales

Mobile app sales