How values are formatted
Three rules cover almost every case. Responses and webhooks send the value verbatim. An affiliate’s status arrives asACTIVE, not
active. Webhook bodies are the stored record spread into JSON, so what you see is exactly what is
stored. Some example payloads shown in the webhook portal render values in lower case for
readability — compare case-insensitively if you want to be safe against that.
A few request fields accept a friendlier form. Where an endpoint takes a status on the way in, it
takes lower-case active or inactive and maps it for you. Those are noted below, on the enums
where they apply.
One enum is genuinely lower case. A coupon’s duration is stored as once, forever, or
repeating. That is not a formatting quirk in the API — it is the stored value, and it mirrors
Stripe’s naming.
Dashboard labels do not always match the stored value. Where they differ, the difference is listed.
Affiliate status
On thestatus field of an affiliate, in affiliate.* webhooks, and on the affiliate objects
embedded in sale and referral payloads.
A new affiliate lands on
ACTIVE if the program approves automatically, and INACTIVE if it does
not. From INACTIVE you approve to ACTIVE or reject to DECLINED. DEACTIVATED and BANNED are
reachable from ACTIVE and are the two states that suppress payouts without deleting history.
When creating or updating an affiliate through the API, the field is
affiliateStatus on the way
in and accepts active or inactive. Anything else, including omitting it, falls back to your
program’s auto-approval setting. The response comes back as status with the upper-case value.Referral status
Stored assubscriptionStatus and exposed as status on both the API and referral.* webhooks.
submissionType sits alongside it and records who created the referral:
Sale status
Sales start
ACTIVE and move to REFUNDED through the refund endpoint or an integration reporting
the refund upstream. There is no path back.
Commission approval status
On every commission, and reflected in the commission amount reported with a sale.
When the status is
ON_HOLD or DECLINED, holdReason says why.
The decision runs in a fixed order. A fraud match wins first, and the program’s fraud action decides
the outcome:
HOLD_FOR_REVIEW produces ON_HOLD, REJECT_AUTOMATICALLY produces DECLINED. With
no fraud match, the applicable plan’s auto-approve setting decides between ACCEPTED and ON_HOLD.
Either result is then overridden if the affiliate is deactivated or banned.
Payout status
The path is
PENDING to PROCESSING to either PAID or FAILED. Payouts settled outside Referly
are marked PAID with manuallyPaid set.
Payout batch status
Batches have their own lifecycle, longer than a single payout’s because it covers funding as well as sending.
A batch can report
PAID while an individual payout inside it reports FAILED. Reconcile against
payouts, not batches.
Payment methods
paymentMethod on affiliates and payouts, and payoutMethod on batches.
paidMethod on a batch records how it was settled: INTEGRATION when a provider sent it,
MANUAL when you did.
Commission shape
paymentTrigger appears on the program, the commission plan, and every sale. A sale with
BONUS or CONTENT_REWARD has no customer payment behind it — it exists so a non-sale reward can
travel through the same commission and payout pipeline.
Reward types
Cash is the default. Everything below describes a program paying in something other than money.rewardType and nonCashRewardType are carried from the commission plan onto the commission, the
payout, and the payout batch, so a non-cash reward is identifiable at every stage.
Tracking method
referralMedium on a referral records how the affiliate was credited.
Source enums
Four separate enums record where a record came from. They are the fastest way to tell apart data you sent from data an integration reported.source on an affiliate:
source on a referral:
source on a sale:
When
source is INTEGRATION, a second field names the platform —
integrationSalesSource on sales, integrationReferralSource on referrals:
JAVASCRIPT, MAKE, ZAPIER, STRIPE, SHOPIFY, WOOCOMMERCE, PADDLE, CHARGEBEE,
MEMBERSTACK, POLAR, SKILLPLATE, ZYLVIE.
A related but distinct enum, integrationType, appears on coupons and payout batches and names the
platform that owns the underlying object: NONE, STRIPE, CHARGEBEE, PADDLE, SHOPIFY,
WOOCOMMERCE, ZYLVIE, POLAR.
Anything you create through the REST API is stamped
API. That makes it straightforward to
reconcile your own writes against everything else in an export.Coupon enums
durationInMonths is only meaningful when duration is repeating.
Commission rule enums
These appear on commission plans and their rule groups. You read them; the API does not write them.ruleCondition decides whether every rule in a group must match or only one of them.
Invoicing enums
Present on affiliates and payouts for programs whose affiliates invoice with VAT.Related
Data model
The objects these values live on, and how they relate.
Tracking parameters
The URL parameters and click fields Referly reads and stores.
Webhook event types
Every event Referly emits and what triggers it.
API reference
Endpoint-by-endpoint documentation, including which fields accept which values.