The same API we build on, now open to you
We’re releasing v2026-08, a new version of the Refersion API, and opening it to outside developers for the first time. It is the API our own merchant app runs on. When you call it, you reach the same endpoints our frontend reaches and get the same behavior back.
What v2026-08 is
v2026-08 is the current version of the Refersion API. It replaces the previous public REST API, which lived at /v2 and is now frozen. The version is a path segment on the API host:
https://api.refersion.com/v2026-08/affiliatesThe name is the month the version was cut. v2026-08 will keep behaving the way it behaves today. If we need to make a change that breaks backward compatibility, that change ships in a new dated version rather than as a silent shift underneath you.
Why API-first matters here
Most companies build the product first and the public API second, as a reduced and delayed reflection of what the UI already does. We built this one the other way around. The new Refersion merchant app is a client of v2026-08. It authenticates the way your integration will and calls the endpoints your integration calls.
The consequence is that there is no second-class public API quietly lagging behind the real one. When our product team ships a feature in the app, the endpoint behind it is already public, because the app had no other way to ship it. We are not claiming that every action in the merchant dashboard has a matching endpoint today. Parity between what a merchant can click and what a developer can call is how this API is designed, and the public surface grows toward it.
What you can build
The current surface covers the objects a merchant integration or an agency tool works with. Affiliates are fully manageable through the API, and so are conversions: reading conversion detail, issuing manual credit, crediting a conversion by order ID, and updating conversion status. Clicks, orders, and offers are queryable resources of their own.
If you’re building around affiliate recruitment, prospects are covered, along with prospect pitches and prospect feedback, so you can run a pipeline of potential affiliates without working through the dashboard by hand. Promotion methods are exposed as well, for tracking how affiliates say they will promote a program.
Authentication
Every request carries a bearer token in the Authorization header. You get that token by exchanging OAuth client credentials for an access token against the auth service:
curl -X POST https://auth.refersion.com/oauth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "your-client-id",
"client_secret": "your-client-secret"
}'The response looks like this:
{
"token_type": "Bearer",
"expires_in": 7776000,
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}Read expires_in from the response rather than assuming a value. Omit token_type in the request and you get a short-lived token that expires in 3600 seconds. Pass "token_type": "long_lived" and you get one that lasts 90 days (expires_in 7776000). Any other value is rejected with an invalid_request error. Choose based on what is issuing the token: a server-side integration that runs continuously can hold a long-lived token, while a process that mints tokens often should stay with short-lived ones.
Once you have a token, send it as a bearer credential on your API calls:
curl https://api.refersion.com/v2026-08/affiliates \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."You generate OAuth clients from the Refersion dashboard, under Settings → Integrations → Refersion API Keys, in the OAuth section, via Generate OAuth Client. The Client Secret is shown exactly once, at creation time, and cannot be retrieved afterward, so save it somewhere durable right away.
Credentials are scoped to a Refersion account rather than to an individual user. A token minted from a given client can only see and act on that account’s data, and there is no path from one account’s credentials into another account’s records. If a secret leaks, revoke the client from the dashboard. That immediately invalidates the client and every token it has issued. Single tokens cannot be revoked on their own, so revoking the client is how you kill a leaked credential.
The API also throttles requests per caller, and a few endpoints carry tighter limits of their own, credential minting in particular, along with some scan-heavy read endpoints. If you’re calling the API at volume, handle 429 responses with backoff rather than assuming a fixed ceiling.
Deprecations
The previous public REST API, served at /v2, is deprecated. It is frozen: still working, but no longer receiving new functionality. New integration work should target v2026-08 instead. Integrations with the /v2 version should begin migrating to v2026-08 today.
GraphQL is deprecated for merchant integrations. If you’re building something for a merchant, build it on the current REST API version rather than GraphQL. One nuance to be precise about: this deprecation does not apply to GraphQL for marketplace users, which remains supported. If your integration sits on the affiliate side of the marketplace, GraphQL is still a supported path. Separately, within GraphQL itself, pageInfo is deprecated and no longer returns accurate results, which matters if you have an existing GraphQL integration that relies on it for pagination.
Webhooks over polling
If your integration needs to react to activity in a merchant’s account, a new conversion or a status change, webhooks handle that without polling. Endpoint management is part of the public API, so you can register, update, and remove webhook endpoints the same way you manage any other resource, instead of configuring them out of band.
Getting started
Generate an OAuth client from the dashboard under Settings → Integrations → Refersion API Keys, save the Client Secret when it appears, and exchange it for a token as shown above. The full reference lives at refersion.dev, generated directly from the API’s own specification, so it reflects the running API rather than a hand-maintained description of it. Alongside the reference you will find an Authentication guide and dedicated Order Tracking and Webhooks sections.
If you’ve integrated against /v2 before, the concepts will be familiar. The difference is that v2026-08 is the surface our own app depends on, so it gets fixed and extended on the same schedule the product does.
