Introduction

Referly is an affiliate platform: it records who referred a visitor, keeps that attribution when the visitor becomes a customer, calculates the commission on every payment they make, and settles it in a payout. These docs cover the parts you build against — the browser tracking script, server-side conversion reporting, the REST API, webhooks, and the platform integrations that replace all of the above.

What you can build

Attribution in the browser

Drop in one script tag and Referly records clicks, stores the referral, and survives across pages and subdomains.

Conversions from your server

Report sales from your backend, where you already know the real amount charged.

Your own affiliate experience

Create affiliates, issue links and coupons, and read performance data from your own app.

Reactions to what happens

Receive an HTTP callback whenever an affiliate, referral, sale, or coupon changes.

Who these docs are for

You are writing code against Referly — installing tracking on a site you control, wiring your checkout to report conversions, or syncing affiliate data into another system. You are comfortable with HTTP requests, JSON, and a bit of JavaScript. If you manage the program itself — commission plans, approving affiliates, running payouts — the Help Center covers that side, and none of it requires code.

How the pieces fit together

Every integration is some combination of three moving parts.

1. Attribution: who referred this person

A visitor arrives through an affiliate’s referral link (or uses their coupon code) and Referly records a click. The tracking script stores that attribution in the browser so it survives page navigation and return visits.

<script
  data-affiliate
  data-program-id="YOUR_PROGRAM_ID"
  src="https://www.referly.so/affiliate-tracker.js"
></script>

Once the script has resolved the referral it exposes it on the page, so your own code can read it and pass it along at checkout:

window.addEventListener("affiliate_referral_ready", function () {
  console.log(window.affiliateRef); // the affiliate's referral code
  console.log(window.affiliateId); // the click this visit belongs to
});

See Install the snippet and the JavaScript API reference.

2. Conversion: this person became a customer

When the visitor signs up or pays, you tell Referly. The click becomes a referral (a tracked customer), and each payment they make becomes a sale that produces a commission. You have three ways to do this, and most programs use exactly one:

An integration

Stripe, Shopify, WooCommerce, Paddle, and others report payments to Referly for you. No conversion code to write.

Your server

Post the sale from your backend after the charge succeeds. The most reliable option when you control the payment flow.

The browser

Call the tracking script’s helpers on your confirmation page. Quickest to ship, but subject to ad blockers and abandoned redirects.

3. Reading and reacting

Once data is flowing, the REST API reads and writes affiliates, referrals, sales, links, coupons, and promotional codes, and webhooks push changes to you as they happen.

Base URL and environments

The REST API lives under a single base URL:

https://www.referly.so/api/v1

The tracking script is served from https://www.referly.so/affiliate-tracker.js. Referly has one live environment — there is no separate sandbox, and API keys are not split into test and live modes. To try things end to end without touching real data, create a second program in your dashboard and point your staging site at that program’s ID. Sales you create while testing can be deleted afterwards.

API access is included with the Business plan. If your key returns 403 with User does not have API access, check your plan on the pricing page.

Authentication

Every API request carries an API key as a bearer token. Keys are created in your dashboard and scoped to one program, so the key itself determines which program’s data you are reading and writing — you never pass a program ID to the API.

curl https://www.referly.so/api/v1/affiliates \
  -H "Authorization: Bearer YOUR_API_KEY"

A missing or unrecognised key returns 401. Full details, including how to generate and rotate a key, are in Authentication.

API keys grant full read and write access to your program. Keep them on your server and out of browser code, mobile apps, and version control.

Rate limits

Requests are counted per API key, and the ceiling depends on what the endpoint does — reads are the most generous, sales the strictest, because each one triggers attribution and commission calculation. Exceeding a limit returns 429 with Too many requests. Please slow down. Retry after a short pause rather than immediately, and batch where you can. The exact windows are listed in Rate limits.

Webhooks

Referly can push events to an endpoint you own, so you do not have to poll. Events are emitted for affiliates, referrals, sales, coupons, and promotional codes, each in created, updated, and deleted form — for example affiliate.created, sale.updated, referral.deleted. Deliveries are signed, retried on failure, and logged, so you can replay anything you missed. See Webhooks.

Skip the code

If you are on a platform Referly already integrates with, the fastest integration is no integration at all.

Getting started

Tracking

Server-side tracking

API

Webhooks

Integrations

Reference

What you can build

Attribution in the browser

Conversions from your server

Your own affiliate experience

Reactions to what happens

Who these docs are for

How the pieces fit together

1. Attribution: who referred this person

2. Conversion: this person became a customer

An integration

Your server

The browser

3. Reading and reacting

Base URL and environments

Authentication

Rate limits

Webhooks

Skip the code

Stripe

Shopify

WooCommerce

Zapier

Make

Everything else

Quickstart

Core concepts

Glossary

API reference

​What you can build

Attribution in the browser

Conversions from your server

Your own affiliate experience

Reactions to what happens

​Who these docs are for

​How the pieces fit together

​1. Attribution: who referred this person

​2. Conversion: this person became a customer

An integration

Your server

The browser

​3. Reading and reacting

​Base URL and environments

​Authentication

​Rate limits

​Webhooks

​Skip the code

Stripe

Shopify

WooCommerce

Zapier

Make

Everything else

​Related

Quickstart

Core concepts

Glossary

API reference

What you can build

Who these docs are for

How the pieces fit together

1. Attribution: who referred this person

2. Conversion: this person became a customer

3. Reading and reacting

Base URL and environments

Authentication

Rate limits

Webhooks

Skip the code

Related