Introduction

Referalli is a partner, affiliate and referral platform. It records where traffic came from, decides which partner gets credit for each new customer, turns that customer's payments into commissions, and pays partners out. Everything the dashboard does goes through the same HTTP API described here.

Base URLs

All examples use the production host:

Send referally-version: 2026-11-01 with every request (see Versioning and changelog); under it, every list is paginated. The OpenAPI document describes the latest version.

Requests and responses are JSON. Money is always an integer in minor units (cents for USD) next to a lowercase three-letter currency, for example "amountMinor": 2000, "currency": "usd".

Core concepts

Organization (org). Your tenant. Every program, partner, click and commission belongs to exactly one org, and data never crosses between orgs. API keys are issued per org. Each org also has a public tracking token (tk_…), returned as trackingToken by GET /v1/org, which identifies it in public tracking URLs.

Program. An affiliate or referral program inside the org (prg_…). It holds the attribution settings: attributionModel (last_click, first_click, position_based or time_decay), cookieWindowDays (default 60) and signupToConversionDays (default 365).

Partner. A person or company that sends you customers (ptr_…), identified by email. Partners join programs through enrollments.

Link. A tracked short link for one partner in one program (lnk_…). Each link has a code and a destinationUrl. The public URL is /go/{trackingToken}/{code}. Partners can also have coupon codes that attribute a sale without any click.

Click. One hit on a tracked link (clk_…, returned as clickId). Every click is fraud-scored and stored, even suspicious ones; suspicious clicks are marked ineligible instead of dropped.

Referral. The decision that a specific customer belongs to a specific partner (ref_…). You create one by calling POST /v1/referrals/associate when a customer signs up, passing your own id for that customer as customerRef. The attribution engine looks at that visitor's clicks, coupon and hashed email and picks a partner.

Conversion. Something a referred customer did that matters commercially: signup, trial, payment, refund or churn. Conversions are derived from your billing provider's webhooks (Stripe, Paddle and others) or from the generic conversion API.

Commission. An amount a partner earned. Commissions live in an append-only ledger of events (earned, approved, paid, reversed, adjusted). Balances are computed from the ledger and are never stored on their own.

Payout. A transfer to a partner that settles their approved commissions, sent through the payout provider your org connected (PayPal, Stripe, Wise, Circle, Payoneer, Tremendous) or exported as CSV.

How the pieces connect

flowchart LR
  A[Partner shares /go link] --> B[Click recorded and fraud-scored]
  B --> C[Visitor lands on your site with ref_click_id]
  C --> D[Your server calls /v1/referrals/associate at signup]
  D --> E[Referral: customer belongs to partner]
  E --> F[Billing webhook: invoice paid]
  F --> G[Commission earned, held, approved]
  G --> H[Payout run settles approved commissions]

Where to go next