Merchant API
Your program's stats and affiliates, and tracking links for approved affiliates, from your own server. The same numbers and rules as your dashboard, because it calls the same code. On the Scale plan.
This is not the Conversions API, which reports sales with a product key (klb_…) and works on every plan. The merchant API reads and creates links; it never touches payouts, statements, activation, terms or payment processors.
Authentication
The account owner creates keys in Settings → API. A key starts with klbm_, belongs to the account (every program it owns), and is shown once: Klibon only stores a hash of it. Send it as a bearer token: Authorization: Bearer klbm_…. An account holds up to 10 live keys; create one per server or tool, so you can revoke one without the others.
Each key carries the permissions chosen when it was created:
stats:read— Clicks, conversions, revenue and commissions per program and per affiliate, over a period.affiliates:read— Each affiliate's status, referral code, email, links, coupon codes and lifetime totals.links:write— Mint a link for an approved affiliate, and remove the links this API created.
curl https://klibon.com/api/v1/merchant \
-H "Authorization: Bearer klbm_your_key"Plan
The plan is checked on every call, not when the key was made. An account that leaves Scale keeps its keys, and they answer 402 with plan_required until it is back on Scale; nothing has to be recreated. Revoking a key takes effect on its next call.
Endpoints
All under https://klibon.com, JSON in and out.
affiliate_id is the affiliate's id on that program, the id the affiliates list returns. Your own test link is never listed and never counted.
Conventions
- Money is in minor units, per currency, and never added up across currencies:
{ "USD": 118900, "EUR": 23800 }is $1,189.00 and €238.00. - Periods are the dashboard's:
rangeis one of7d,30d,90d,12m(default30d).tzis the IANA zone days are cut in (default UTC; an unknown one falls back to UTC and the answer says so).currencypicks the currency EPC and the top affiliates are ranked in, the program's own by default. - Dates are ISO 8601 in UTC, except a series'
date, which is the local day its bucket starts on. - Lists take
page(from 1) andper_page(default 25, at most 100) and answerdata,page,per_page,totalandhas_more. Everything else answers{ "data": … }. - Lifetime totals are an affiliate's whole time on the program: genuine clicks, conversions, attributed revenue before refunds, and commissions earned (pending, approved and paid; reversed ones are out).
Stats
curl "https://klibon.com/api/v1/merchant/programs/PROGRAM_ID/stats?range=30d&tz=Europe/Paris" \
-H "Authorization: Bearer klbm_your_key"{
"data": {
"program_id": "5d1c…",
"range": "30d",
"granularity": "day",
"tz": "Europe/Paris",
"period": { "start": "2026-10-19", "end": "2026-11-18" },
"previous_period": { "start": "2026-09-19", "end": "2026-10-19" },
"currency": "USD",
"currencies": ["USD", "EUR"],
"totals": {
"clicks": 1840,
"flagged_clicks": 37,
"conversions": 41,
"revenue": { "USD": 118900, "EUR": 23800 },
"commissions": { "USD": 35670, "EUR": 7140 },
"commissions_by_status": { "USD": { "pending": 9870, "approved": 15800, "paid": 10000 } }
},
"previous_totals": { "clicks": 1512, "…": "…" },
"conversion_rate": 0.0223,
"epc": { "USD": 19.4 },
"series": [
{ "date": "2026-10-19", "clicks": 61, "flagged_clicks": 1, "conversions": 2, "revenue": { "USD": 5800 }, "commissions": { "USD": 1740 } }
],
"top_affiliates": [
{ "affiliate_id": "a3f0…", "display_name": "Ada", "commissions": 12000, "revenue": 40000, "conversions": 14, "last_activity": "2026-11-17T09:12:00.000Z" }
]
}
}Affiliates
status filters the list: all (default), pending, approved, rejected or removed.
curl "https://klibon.com/api/v1/merchant/programs/PROGRAM_ID/affiliates?status=approved&per_page=50" \
-H "Authorization: Bearer klbm_your_key"{
"data": [
{
"id": "a3f0…",
"status": "approved",
"referral_code": "ada",
"display_name": "Ada",
"email": "[email protected]",
"website": "https://ada.dev",
"source": "marketplace",
"joined_at": "2026-09-02T14:20:11.000Z",
"approved_at": "2026-09-02T14:20:11.000Z",
"removed_at": null,
"live_links": 2,
"live_coupons": 1,
"totals": {
"clicks": 3110,
"conversions": 58,
"revenue": { "USD": 168200 },
"commissions": { "USD": 50460 },
"commissions_by_status": { "USD": { "pending": 4200, "approved": 6260, "paid": 40000 } }
}
}
],
"page": 1,
"per_page": 50,
"total": 1,
"has_more": false
}Tracking links
A link you create belongs to the affiliate like one they made themselves: it shows in their list, carries their code and pays them. The rules are the same too. The affiliate must be approved, the destination must be on your product's domain, and an affiliate has a limit on live links and on links ever created for one program. The link uses your own tracking domain when the program has one serving and your plan includes it, and go.klibon.com otherwise.
curl -X POST https://klibon.com/api/v1/merchant/programs/PROGRAM_ID/affiliates/AFFILIATE_ID/links \
-H "Authorization: Bearer klbm_your_key" \
-H "Content-Type: application/json" \
-d '{
"destination_url": "https://acme.com/pricing",
"label": "Black Friday newsletter",
"slug": "ada-black-friday"
}'{
"data": {
"id": "0b7e…",
"url": "https://go.klibon.com/r/ada-black-friday",
"destination_url": "https://acme.com/pricing",
"label": "Black Friday newsletter",
"slug": "ada-black-friday",
"clicks": 0,
"last_click_at": null,
"created_at": "2026-11-18T10:02:44.000Z",
"archived_at": null,
"created_via": "api"
}
} To retry a create safely, send a slug: a second call with the same one answers 409 instead of creating a second link.
DELETE removes a link from the affiliate's list, only one the API created (created_via: "api"); a link the affiliate made is theirs and answers 403. A removed link keeps redirecting and tracking, so nothing already shared breaks, and its clicks stay. Every create and removal is recorded under Settings → Agents, with the key's name.
Rate limits
120 calls a minute per key, of which 30 may be writes. Past that, the answer is 429 with a Retry-After header in seconds.
Errors
Every refusal of the key carries a stable data.code to branch on; the message is for people and may change.
401missing_key— No Authorization header.401product_key— A Conversions API key (klb_…) was sent. This API takes an account key (klbm_…).401invalid_key— The key is unknown or revoked.402plan_required— The account is not on Scale. The key is kept and works again once it is.403insufficient_scope— The key lacks the permission this endpoint needs.429rate_limited— Too many calls this minute. Wait for Retry-After seconds.404— the program, affiliate or link is not on this account.409— the affiliate is not approved, a link limit is reached, the slug is taken, or the program is a listing Klibon does not track.422— the body or query did not validate. The message says which field.
{
"statusCode": 402,
"statusMessage": "The merchant API is part of the Scale plan. …",
"data": { "code": "plan_required" }
}