https://www.referly.so/api/v1. Send Authorization: Bearer YOUR_API_KEY and, for JSON bodies, Content-Type: application/json.
Permissions and program selection
Keys have resource-specific read and write permissions and optional expiry. Read and write scopes are independent. See authentication. Requests default to the key’s original program. On operational endpoints,X-Program-Id can select a program created by that exact key. It does not grant access to other existing programs in your account. Legacy affiliate, referral, sale, link, coupon and promotional-code endpoints continue to use their usual program key.
Pagination
List operations returndata and nextCursor. Send limit from 1 to 100 (default 50), then pass the returned cursor in the next request. Stop when nextCursor is null.
GET /payout-batches, explicitly send pagination=cursor. Omitting it preserves the legacy latest-50 array. Other legacy list responses are unchanged.
Retry writes safely
Operational writes accept an optionalIdempotency-Key: 8–200 printable ASCII characters, with no spaces. Keep the same key, method, path and validated payload when retrying a request. A completed operation returns its saved result; using its key for a different request returns 409 idempotency_conflict. Keys are unique within the selected program across routes.
Without a key, retrying configuration creates or webhook operations can repeat the operation. Commission adjustments also deduplicate on sourceReference, and manual settlement checks the batch’s recorded state and payment details.
Concurrent operations can return 409; retry with backoff and the original request. Webhook mutations can remain pending while a 90-second provider-call lease is active. Reconcile unusually old unresolved provider operations before retrying them.
Legacy sale reporting still deduplicates using externalId or externalInvoiceId. See sale idempotency.
Responses and errors
Operational responses carryX-Request-Id; normal success and error responses use Cache-Control: no-store. JSON bodies are limited to 64 KiB. Unknown mutation fields are rejected. See errors and rate limits.