The object graph
A referral moves left to right through this chain. Each step creates a row that points back at the one before it, which is how Referly can answer “who earned this, and why” for any amount it pays out. Two objects sit outside the chain but feed into it. Coupons and promotional codes give an affiliate a second way to be credited, without a link or a click. Commission plans decide how much a sale is worth, and are attached to the affiliate rather than to the sale. Everything below is scoped to a single program. Your API key is issued for one program, so you never pass a program ID to the REST API — the key already identifies it.Program
The container for everything else. One program means one affiliate portal, one currency, one attribution window, and one API key.
Programs are not exposed as a REST resource. You read and configure them in the dashboard; the API
operates inside whichever program your key belongs to.
Affiliate
A person promoting your product. Affiliates are created when someone signs up through your portal, when you import them, or when you call the API.
An affiliate belongs to exactly one program. The same person promoting two of your programs is two
affiliate records with two IDs.
Affiliate link
The referral link itself. An affiliate can hold several, which is how you attribute the same person across different campaigns or landing pages.
The pair
programId plus link is unique, so a slug can be reused across programs but never within
one.
Click
A visit that arrived with affiliate attribution. Clicks are what the tracking script writes, and they carry the richest context of any object in the model.
Clicks have a composite identity of
id plus createdAt, because the table is partitioned by time.
There is no click endpoint on the REST API — clicks reach you through dashboard analytics, exports,
and postbacks. The full capture list is documented in
Tracking parameters and
What gets captured.
Add-to-cart events are recorded as their own rows against the originating click, so mid-funnel
activity can be reported without waiting for a sale.
Referral
A customer that an affiliate brought in. A referral is created the first time you tell Referly that a tracked visitor converted — signed up, started a trial, or paid.
The uniqueness rule is
email plus program. That is what makes conversion reporting safe to retry —
see Idempotency.
Sale
One payment by a referred customer. A referral has many sales: the first order and every renewal, upgrade, or repeat purchase after it.
Posting a sale with an
externalId you have already used updates that sale instead of creating a
duplicate. See Reporting sales.
Commission
What an affiliate earned from a sale. Commissions are created by Referly, never by you directly — you report the sale and Referly prices it from the affiliate’s commission plan.
A single sale can produce more than one commission. When your program has multi-tier rewards
enabled, the affiliate who recruited the selling affiliate earns from the same sale, and so can the
tier above them. That is why the API surfaces
commissionEarned for the sale’s own affiliate rather
than a sum.
Performance bonuses, contest prizes, and content rewards also produce commissions, with no sale
revenue behind them. They are how non-sale earnings enter the same payout pipeline.
Commissions have no REST resource of their own. You read them through the sale that produced them
and through payouts.
Payout
Money owed to one affiliate for a period. A payout gathers the commissions that were payable when it was generated and freezes them into a single amount.Payout batch
A group of payouts processed together — one program, one payment method, one period. Batches are the unit you approve and fund, and the only payout object with a REST endpoint.
A payout can fail while its batch succeeds, so check both statuses when reconciling.
Coupon and promotional code
The second way an affiliate gets credit. A coupon is the discount itself; a promotional code is a redeemable string pointing at that coupon. One coupon can back many codes, which is how every affiliate can have a personal code that grants the same discount. Coupon
Promotional code
When a sale arrives carrying a promotional code, Referly attributes it to that code’s affiliate even
if there was never a click. See
Coupons and promotional codes.
Pricing objects
These decide what a sale is worth. They attach to the affiliate, not the sale, and are resolved at the moment commission is calculated.
A plan can pay cash or a non-cash reward — account credit, a coupon, or a free product — and the
resulting commission carries the reward type through to the payout.
Identifiers at a glance
Use your own identifiers, not Referly’s, as the join key in your system. They are what make retries
safe and what let you reconcile without storing Referly IDs.
Where each object appears
Webhook payloads embed related objects rather than making you fetch them — a
sale.created body
carries the sale, its affiliate, its referral, its commission amount, and its payout if one exists.
See Payload structure.
Related
Statuses and enums
Every status value these objects can hold, and what each one means.
Tracking parameters
The URL parameters and click fields Referly reads and stores.
Core concepts
How attribution, conversion, and settlement fit together.
API reference
Endpoint-by-endpoint documentation for every resource above.