Skip to content
Sign inBecome a partner
Get startedOverview
Documentation
Developer docs · API v1

Build with Flow Affiliate

Track who referred whom, pay partners for real results and reward the people who invite their friends. Your backend reports what happens; Flow Affiliate attributes it, applies the program rules and tells you what to credit.

Start the quickstartAPI reference
Sandbox key
fg_test_…
Production key
fg_live_…
Every request
HMAC-SHA256

Three calls, in order

The guide
  1. AskPOST /v1/attributionscreateAttribution()

    Before sign-up. Answers at once, with an attributionKey.

  2. Confirmuser.registeredtrack()

    The user is new: the key attributes them to the partner.

  3. Reportpurchase.completedtrack()

    What they do next. The program’s rules pay on these.

Node · @flow/growth-sdk
// Ask: before sign-up
const ask = await fg.createAttribution({ url, installId });
const key = ask.ok && ask.data.attributable
  ? ask.data.attributionKey
  : undefined;

// Confirm: the user is new
await fg.track({
  type: 'user.registered', attributionKey: key,
  eventId: `registered:${user.id}`, appUserId: user.id,
});

// Report: what they do next
await fg.track({
  type: 'purchase.completed', attributionKey: key,
  eventId: `order:${order.id}`,
  amount: order.total, currency: 'USD',
});
5 minutes

Quickstart

Send your first signed event from the sandbox and watch it get attributed.

Reference

API reference

Every endpoint, field and error code, with curl and Node examples.

How it works

A partner (a creator, a publisher or one of your own users) shares a tracking link or an invite code. Someone clicks it, installs your app or opens your site, and signs up. From there:

  1. The click is recorded. Every tracking link opens through /a/<code>, which records the click and sends the visitor on with two query parameters: fg_click (the click id) and fg_ref (the partner's code).
  2. Your backend asks. Your app hands over what it was opened with (the link, your deep-link SDK's params or a typed code) and your server asks POST /v1/attributions. The answer comes at once, before sign-up, with an attribution key.
  3. Your backend confirms and reports. Once you know the user is new, user.registered with the key confirms the referral. Every later event (a purchase, a new subscription, one of your own events) carries the key, and those are what the program's rules pay on.
  4. Flow Affiliate decides who earns what. It attributes the registration to the right partner, applies the rules that were on offer when the link was clicked, and creates the partner's commission or the in-app reward your app should credit.

Nothing that creates money is decided in the browser or the app: attribution and payouts follow only from events your servers sign.

Choose your integration

Any language

Server-to-server events

Sign plain HTTPS requests with HMAC-SHA256 from your backend. Works from any stack.

Node 18+

Node SDK

@flow/growth-sdk signs, retries with backoff, verifies webhooks and never throws unless you ask it to.

For publishers

Partner API

Partners pull their links, conversions and earnings with a Bearer key from the portal.

Server-to-server events are the foundation. Your backend calls POST /v1/events with a key id and a signature over the exact request body. Everything else (asking about a referral, opening the hosted share studio, linking accounts) is the same signed API.

The Node SDK wraps that API for Node backends. It is the quickest way to integrate and the reference for what a well-behaved client does: stable event ids, retries with fresh signatures, and errors returned as values so an outage on our side never fails a request on yours.

The partner API is the other side of the platform. Publishers and agencies create links and read their results programmatically with a key that starts with fa_live_ or fa_test_. If you are integrating an app or a shop, you won't need it.

Sandbox and production

Every app has two kinds of key. Keys that start with fg_test_ sign sandbox traffic: events create conversions, commissions and rewards that you can inspect, but they are never settled, paid or shown to partners. Keys that start with fg_live_ sign production traffic, which creates real liability. Build and test against the sandbox; switch the key when the integration checklist is green.

Where to go next

  • New here? Start with the Quickstart, then read Concepts for the model behind attribution, commissions and rewards.
  • Integrating an app? Attribution for apps walks through the three calls, ask, confirm and report, from the first open to revenue, and Links into your app shows how a link carries its code into the app.
  • Sending events? Events covers the fields, idempotency, batching and reversals.
  • Crediting users? Webhooks explains reward delivery, signatures and retries.