Concepts

The model behind every integration: how a click becomes an attributed user, how rules turn that user’s actions into commissions and rewards, and how sandbox and production stay apart.

The pieces

App: your product. Each app has its own keys, settings and event history.
Program: a way to grow the app through referrals, such as an affiliate program for creators or a friend-referral program for your own users. A program sets the attribution window and model.
Campaign: the terms of a program for a market or a period: its currency, budget and rules (what pays, how much and to whom).
Partner: whoever refers people. A creator or publisher with a cash payout, or one of your own users referring friends.

Every partner gets a tracking link, https://go.affiliate.yflow.io/a/<code>. The code at the end is also an invite code a person can type into your app. Codes are letters and digits and match without regard to case.

Opening a link records a click and sends the visitor straight on. Where a link adds parameters, they are fg_click (the click id) and fg_ref (the code):

iPhoneredirect

The app's App Store page. Nothing survives an App Store install: install matching, if the app turns it on, matches the first launch to the click as a probable match, and the app's code field catches the rest. With an App Store provider token, the link carries Apple's campaign parameters, so App Store Connect counts downloads per publisher.

Androidredirect

Google Play, with fg_click=…&fg_ref=… in the install referrer. Your app reads it after install (the Play Install Referrer API).

Phone, by your choiceredirect

Your App Clip (iPhone), or your own universal link with both parameters, only when you choose it as the route. An installed app opens the link directly once you add your app IDs.

Computerredirect or page

For an app with a website: the link's destination, or the app's landing page, with fg_click and fg_ref added. For an app-only app: a page with the link as a QR code, to open it on the phone.

Clicks and touches

A touch is anything that can earn a partner a user:

a click: someone opened a tracking link. Its id is the fg_click value, a UUID.
a code claim: your backend asked about a code or click and got an attribution key, a user who already has an account entered an invite code, or your registration event carried one in affiliateCode.

A user who already has an account claims a code with POST /v1/affiliates/claim. If their registration arrived earlier and was ignored for lack of a touch, it is processed again as soon as the claim lands.

Attribution keys

Your backend asks about what the app caught with POST /v1/attributions, usually at first open and before sign-up. A yes records a code claim and hands back its attribution key, fga_…. From then on the key is the referral:

user.registered with the key and an appUserId confirms it: the key is bound to that user, and its touch wins the attribution;
every later event may carry the key instead of appUserId;
a key not confirmed within the program's attribution window expires. You can also decline it, so the publisher sees why.

A key works only with your app's own signed credentials, in the environment it was made in. Asking with the same installId again answers with the same key.

Attribution

Attribution happens on one event: user.registered. It looks at every touch that could explain the registration (the one named by attributionKey, the click named by clickId, the code in affiliateCode, and claims already bound to the appUserId) and keeps the ones that are eligible:

the touch is inside the program's attribution window: 30 days unless the program sets another;
a click happened before the registration (up to five minutes of clock difference is allowed). A code may be claimed after sign-up, within the window;
the program is active, the partner is an active member and not suspended, and a campaign is open.

A touch named by the registration's attributionKey wins whenever it is eligible: you chose it. Otherwise, when several touches qualify, the program's attribution model picks one:

last_touchdefault

The most recent eligible touch wins.

first_touch

The earliest eligible touch wins.

referral_code_priority

A code claim beats any click; among claims, the most recent wins.

The result is a conversion, at most one per app user and environment. The terms it pays under are the ones on offer when the winning link was clicked, so a later change to the rules never changes what an earlier referral earns.

Conversions and rules

After attribution, the events you send for that user are matched against the campaign's rules. A rule names a trigger event from the app's event catalog (purchase.completed, subscription.started, or one of the app's own events such as level.completed) and pays either a fixed amount or a percentage of the event's amount. A rule can pay once or on every occurrence, and can wait a hold period before its payout is approved.

A conversion moves through qualification_pending → qualified once a rule pays for it. It can also end as rejected (by a risk check or a person) or reversed (when the event it depended on is undone).

Commissions and rewards

A rule pays one of two kinds of money. Which one depends on who it pays:

Commissionpartner cash

What a creator or publisher earns. Commissions go from pending_review to approved, are settled monthly with a statement and paid by bank transfer. Partners see them in their portal and through the partner API.

Rewardin-app value

What one of your users earns: the friend who referred someone, or the new user themselves. Flow Affiliate decides the amount; your app credits it when the reward webhook asks. A reward goes from pending to approved to delivered once your app acknowledges it.

Amounts are always integers in minor units (cents) with an ISO 4217 currency code. The network pays in USD. There are no floats anywhere in the API.

Environments

Productionfg_live_ keys

Real users, real conversions and real liability. Commissions are settled and paid; rewards go to your production webhook URL.

Sandboxfg_test_ keys

The same processing, kept apart: sandbox conversions, commissions and rewards are never settled, paid or shown to partners. Rewards go to your sandbox webhook URL only.

The key you sign with decides the environment; the API host is the same. Clicks on tracking links are real traffic and belong to no environment, so a sandbox registration can be attributed to a click on a real link.