# Referalli

> Referalli is an attribution-first affiliate and referral platform. Partners share tracked links; Referalli attributes visitors and signups to them, turns billing events from the merchant's own payment provider into commission lines on an append-only ledger, and pays partners through the merchant's own payout provider. Everything the dashboard does is available through the `/v1` REST API at https://referalli.com.

Key facts for integrating:

- Server calls authenticate with a secret API key: `Authorization: Bearer rk_live_...` or `rk_test_...` (test mode, separate data). Never put an `rk_` key in a browser or mobile app; those use the public tracking token (`tk_...`).
- Pin the API version with the `Referalli-Version` header (latest `2026-11-01`). `Referalli-Mode: test|live` asserts the mode.
- Money is integer minor units (`amountMinor: 1980` is $19.80). Send an `Idempotency-Key` on every POST.
- The key call at signup is `POST /v1/referrals/associate` with `programId`, `customerRef` (the id your billing provider sees), and the `anonId` / click id from the `referalli_ctx` cookie.
- Webhooks are Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`, plus `x-referalli-topic`); verify the raw body and reject deliveries older than 5 minutes. 33 topics.
- Lists are cursor-paginated: `{ object: "list", data, has_more, next_cursor }`, follow with `starting_after`.

## Docs

- [Your first referral in 5 minutes](https://referalli.com/docs/first-referral): install the SDK, create a partner link, capture the click in Node or Next.js, attribute a signup
- [Quickstart with curl](https://referalli.com/docs/quickstart): the whole pipeline with plain HTTP, through to a commission
- [Introduction](https://referalli.com/docs/introduction): the objects (programs, partners, links, referrals, commissions, payouts)
- [Authentication](https://referalli.com/docs/authentication): API keys, scopes, sessions
- [Errors and limits](https://referalli.com/docs/errors-and-limits): the error envelope, every error code, rate limits, retries
- [Versioning](https://referalli.com/docs/versioning): API versions and the changelog
- [Pagination](https://referalli.com/docs/pagination)
- [Test mode](https://referalli.com/docs/test-mode)
- [Tracking script](https://referalli.com/docs/tracking-script): aff.js and the referral cookie
- [Associating customers](https://referalli.com/docs/associating-customers): attributing signups
- [Attribution](https://referalli.com/docs/attribution)
- [Conversions](https://referalli.com/docs/conversions): billing events and the generic conversion API
- [Commission rules](https://referalli.com/docs/commission-rules)
- [Payouts](https://referalli.com/docs/payouts)
- [Webhooks](https://referalli.com/docs/webhooks): delivery format, verification in every language, all event topics
- [Billing providers](https://referalli.com/docs/billing-providers): Stripe, Paddle, Lemon Squeezy and others
- [Auth platforms](https://referalli.com/docs/auth-platforms)

## SDKs

- [SDKs overview](https://referalli.com/docs/sdks): install table and quickstarts for every language
- JavaScript/TypeScript: `npm install referalli` (`import { Referalli } from 'referalli'`), https://github.com/Referalli/referalli-js
- [React and Next.js](https://referalli.com/docs/react-and-nextjs): `@referalli/react`, `@referalli/next`; Express: `@referalli/express`
- Python: `pip install referalli` (`from referalli import Referalli`), https://github.com/Referalli/referalli-python
- Go: `go get github.com/referalli/referalli-go` (`referalli.New(apiKey, opts...)`)
- Ruby (`referalli` gem), PHP (`referalli/referalli-php`), Kotlin (`com.referalli:referalli-kotlin`): https://github.com/Referalli
- [Mobile apps](https://referalli.com/docs/mobile): Swift package `Referalli` (https://github.com/Referalli/referalli-swift), Android `com.referalli:referalli-android`, `@referalli/react-native`
- [Example apps](https://github.com/Referalli/referalli-examples): Next.js, Express, Flask, Go net/http, Expo

## API specification

- [OpenAPI 3.1, JSON](https://referalli.com/v1/openapi.json): every operation, schema, error response and webhook topic
- [OpenAPI 3.1, YAML](https://referalli.com/v1/openapi.yaml)
- [OpenAPI and Postman](https://referalli.com/docs/openapi): the Postman collection and client generation
- [referalli-openapi](https://github.com/Referalli/referalli-openapi): versioned spec copies and the Postman collection

## Tools for agents and developers

- [MCP server](https://referalli.com/docs/mcp): `npx -y @referalli/mcp` with `REFERALLI_API_KEY`; Claude Code: `claude mcp add --transport stdio --env REFERALLI_API_KEY=rk_test_... referalli -- npx -y @referalli/mcp`. Write tools need a confirmed second call.
- [CLI](https://referalli.com/docs/cli): `npm install -g @referalli/cli`; `referalli login`, `referalli listen --forward-to <url>`, `referalli trigger <topic>`, `referalli events tail`

## Optional

- [Full docs as one file](https://referalli.com/llms-full.txt)
- [Guides](https://referalli.com/guides): migrating from other affiliate tools
- [Status](https://referalli.com/status)