Skip to main content
GET
Get affiliate stats
Your referral code, your commission rates, lifetime totals, and a month-by-month breakdown of what you earned and what has been paid out. Required scope: affiliates:read.

Scoping

This endpoint always reports on the workspace that issued the API key. There is no path, query or body parameter for a company id, and passing company_id returns 400 rather than silently reporting your own numbers back to you. To read a different workspace’s affiliate stats, use a key issued by that workspace.

Query parameters

There is no request body.

Money is integer US cents

Every field ending in _cents is a whole number of US cents. Divide by 100 for dollars; never parse it as a decimal. That includes payout_sent_cents and paid_cents — a payout wired in another currency is converted at the rate recorded on that payout and stored in US cents, so the whole payload is one currency.

Earned vs payable — the distinction that matters

Commission is earned at the moment a referred customer pays, but it only becomes payable after hold_days have elapsed — that window covers card disputes and refunds, so money that could still be reversed never appears as owed. A recent month therefore reads commission_cents higher than payable_commission_cents; the gap closes on its own as the hold elapses. Nothing is lost.
outstanding_cents can be negative. That means a payout ran ahead of the hold window — you have been paid for commission that has not cleared yet. It is a real state, not an error, and it is deliberately not clamped to zero so an overpayment stays visible. It works itself off as more commission becomes payable. Render it as an “overpaid” state rather than as a negative currency amount.

Response fields

Month rows

Any *_cents field in a month row can be negative. A refund or chargeback is booked in the month it happens, and it reverses the commission at the rate that applied when the customer originally paid — so a month with more refunds than sales reads negative. The summary totals already account for it. Do not clamp these to zero; a table that hides a reversal will not add up to earned_cents.

Rates are not retroactive

commission_rate_pct and override_rate_pct are the rates in force today. Each commission was priced at the rate in force on the day that customer paid, and a later rate change never re-prices what you already earned — up or down. So this does not hold, and you should not present it as if it did:
If your rate moved from 5% to 10% last month, revenue from before then is still priced at 5% and the two numbers will disagree by a wide margin. direct_earned_cents and override_earned_cents are the authoritative figures; the rate fields tell you what the next dollar earns. For the same reason, the per-line rounding is done at the (customer, month) grain, so sum(months[].commission_cents) can differ by a cent or two from a rate applied to a lifetime revenue total. The reconciliation identity below is the one that always holds.

Reconciling the table to the lifetime total

summary is lifetime and unbounded; months[] is a trailing window. They differ, and the payload tells you by exactly how much:
Render earned_before_window_cents as an “Earlier” row and your table always adds up. Widen the window with months if you want the older months itemised.

Example request

Example response

Read on 2026-09-15, for an affiliate on 10% direct, 2.5% override, 30-day hold, whose rates have never changed — which is why revenue times rate happens to reproduce the earned figures here. Do not rely on that in general; see Rates are not retroactive.
Read that payload in the right order. earned_cents is 3,650¢, but all 2,200¢ of it earned in September — a 1,200¢ direct commission and a 1,000¢ override — is younger than the 30-day hold, so payable_commission_cents is 0 for that month and payable_cents is only the 1,450¢ accrued before the window. 700¢ of that has been paid, so the amount actually owed today is outstanding_cents = 750¢. Come 2026-10-05 the September lines age past the hold and payable_cents jumps to 3,650¢ with no new revenue at all. The reconciliation also holds: earned_before_window_cents (1,450) + 2200 + 0 = earned_cents (3,650).

Errors

Authorizations

Authorization
string
header
required

Your Yappr API key (e.g. ypr_live_...). Generate one in the dashboard under Settings → API Keys.

Query Parameters

months
integer
default:12

How many trailing months months[] should cover. Does not affect summary, which is lifetime.

Required range: 1 <= x <= 60

Response

Affiliate stats

Affiliate commission summary for the API key's own workspace. All money is integer US cents — divide by 100 for dollars, never parse as a float.

ref_code
string

Your referral code. Your link is https://app.goyappr.com/signup?ref=<ref_code>.

Example:

"AB12CD34"

commission_rate_pct
number

Your direct (tier-1) commission rate as a percentage, as it stands today. Every past commission was priced at the rate in force on the day that customer paid, so after a rate change referred_revenue_cents * commission_rate_pct will NOT reproduce direct_earned_cents. Use it to say what new revenue will earn — never to re-derive history.

Example:

10

override_rate_pct
number

Your override (tier-2) rate on revenue from your sub-affiliates' customers, as it stands today. 0 when you have no tier-2 terms. Same caveat as commission_rate_pct: it does not re-derive override_earned_cents.

Example:

2.5

hold_days
integer

Days a commission must age before it becomes payable. Covers the card-dispute window. 0 means commission is payable as soon as it is earned.

Example:

30

months_window_months
integer

How many trailing months months[] covers — echoes the months query parameter.

Example:

12

summary
object

Lifetime totals. Unbounded — not limited to months_window_months.

months
object[]

Newest month first, months_window_months entries, zero-filled for months with no activity.