API v2: what's new and how to upgrade
· Edward Karlsson
When we started Affilibee, the API had one job: let your platform tell us that an order happened. That single endpoint was enough to prove the idea of a headless affiliate system, where your backend reports purchases and no tracking script ever touches your storefront.
But reporting orders is only half of running an affiliate program. From the start, our goal has been that merchants can run the whole program from their own systems: affiliates signing up on your own site, and commissions showing up in your own back office, instead of everyone being sent to a separate platform. API v2 is the biggest step so far in that direction.
From one endpoint to seventeen
Version 1 had a single endpoint for creating orders, plus a separate endpoint for test orders. Version 2 has 17 endpoints, grouped around the parts of a program you actually work with:
- Orders. Create orders as before, and now also list them, fetch a single order, update its shipping value, and cancel it. A cancelled order's commission drops to zero. Orders that are already part of a payout, or more than a month old, can't be cancelled.
- Affiliates. List your affiliates (optionally filtered by tier), fetch a single affiliate, invite new affiliates by email, and look up the invitations you've sent.
- Affiliate requests. List the people who have applied to your program, filtered by status, and accept or decline them, with an optional message. You can build the approval step into your own back office instead of logging in to ours.
- Tiers and segments. Read your commission tiers and product segments, so your own systems can show which rates apply to whom.
Every endpoint is documented in the API reference, with example requests in several languages and example responses for both success and errors.
Responses you can rely on
In v1, the shape of a response depended a little on what happened. Successful requests returned a message and some data, and validation errors were tucked inside data.errors.
In v2, every response from every endpoint follows the same envelope:
{
"success": true,
"data": {
"order": {
"uuid": "9c8b7f6a-5d4e-3c2b-1a0f-9e8d7c6b5a4f",
"order_no": "ORDER-1001"
}
},
"errors": null,
"meta": {
"trace_id": "20260321:api:abc12"
}
}
success tells you whether the request worked, data holds the result, and errors holds validation messages when something is wrong. Your integration can parse every response with the same few lines of code.
The meta.trace_id is the small detail we're most pleased with. Every request gets its own trace ID. If something looks off, send us that ID and we can find the exact request, what you sent, and what we answered, without a back-and-forth about timestamps.
Test without touching real data
In v1, testing meant calling a separate test endpoint. In v2, every endpoint has a sandbox twin under /api/v2/sandbox/, backed by its own isolated data.
When you create an API token under Settings → API Tokens, you choose whether it's a live token or a testing token. Testing tokens only work against the sandbox, and live tokens only work against the live API. Use a token against the wrong environment and the request is rejected with 403 Forbidden before anything is read or changed. An integration under development simply cannot create a real order or affect a real commission by mistake.
Read more in Authentication and Testing your integration.
Try it in five minutes
To get from reading to sending requests quickly, we publish ready-made Postman collections for both sandbox and live. Every request comes pre-filled with working example values. Add your testing token and you can create an order, fetch it, update it, and cancel it without writing any code.
What stays the same
Upgrading doesn't mean rewriting your integration:
- Authentication still uses a Bearer token in the
Authorizationheader. - Rate limits are still 60 requests per minute per merchant.
- Creating orders takes exactly the same payload as in v1: affiliate slug, order number, currency, order rows, and customer, with amounts in the smallest currency unit, such as cents.
Upgrading from v1 in four steps
- Switch the path. Every v2 endpoint lives under
/api/v2/, so/api/orders/createbecomes/api/v2/orders/create. - Read the new envelope. Check
success, read results fromdata, and read validation messages fromerrorsinstead ofdata.errors. - Log the trace ID. Store
meta.trace_idalongside your own order, so support questions can point at the exact request. - Move testing to the sandbox. Create a testing token and point your test environment at
/api/v2/sandbox/instead of the v1 test endpoint.
In practice, the request barely changes:
# v1
curl -X POST https://affilibee.com/api/orders/create \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d @order.json
# v2
curl -X POST https://affilibee.com/api/v2/orders/create \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d @order.json
Reading the response is where the envelope pays off:
const response = await fetch('https://affilibee.com/api/v2/orders/create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.AFFILIBEE_TOKEN}`,
'Content-Type': 'application/json',
Accept: 'application/json',
},
body: JSON.stringify(order),
});
const { success, data, errors, meta } = await response.json();
if (!success) {
console.error('Affilibee rejected the order', errors, meta.trace_id);
} else {
saveAffilibeeReference(order.order_no, data.order.uuid, meta.trace_id);
}
The upgrade guide has the full details.
What happens to v1
Nothing, for now. Version 1 keeps working exactly as it does today for at least another year, and we won't switch it off until everyone has had the chance to migrate. If you're still on v1, there's no rush, but new integrations should start on v2, and every new endpoint will only be added there.
Behind the scenes
I built most of the v2 API, while Johan set up the documentation pages that every endpoint is described on: the reference layout, the request and response examples, and the navigation you use to find your way around. Building the endpoints and the docs side by side meant nothing shipped without documentation, and writing the docs often showed us where an endpoint could be simpler.
What's next
API v2 isn't finished. Our aim is that everything you can do in the Affilibee dashboard, you can also do through the API, so you can build the affiliate experience into your own site and back office. That means more endpoints to complete the picture. Webhooks are also high on our wish list, so your systems can hear about new orders, affiliate requests, and commission changes the moment they happen, instead of asking for them. We're not making promises about dates yet, but that's the direction.
If you're integrating and something is missing from the API, tell us. It directly shapes what we build next.
— Edward
