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
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.

GET /api/v1/merchantany
Which key this is and its permissions. Call it first to check a key.
GET /api/v1/merchant/programsany
Every program the account tracks, archived ones included. The ids every other endpoint takes.
GET /api/v1/merchant/programs/:program_id/statsstats:read
Clicks, conversions, revenue and commissions over a period, as totals, the period before, a series and the top affiliates.
GET /api/v1/merchant/programs/:program_id/affiliatesaffiliates:read
The program's affiliates, newest first, each with status, referral code and lifetime totals. Paginated.
GET /api/v1/merchant/programs/:program_id/affiliates/:affiliate_idaffiliates:read
One affiliate: lifetime totals, links, coupon codes and where their traffic comes from.
GET /api/v1/merchant/programs/:program_id/affiliates/:affiliate_id/statsstats:read
One affiliate's numbers over a period.
GET /api/v1/merchant/programs/:program_id/affiliates/:affiliate_id/linksaffiliates:read or links:write
The affiliate's tracking links, live first, removed ones after.
POST /api/v1/merchant/programs/:program_id/affiliates/:affiliate_id/linkslinks:write
Create a tracking link for an approved affiliate.
DELETE /api/v1/merchant/programs/:program_id/affiliates/:affiliate_id/links/:link_idlinks:write
Remove a link the API created from the affiliate's list.

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: range is one of 7d, 30d, 90d, 12m (default 30d). tz is the IANA zone days are cut in (default UTC; an unknown one falls back to UTC and the answer says so). currency picks 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) and per_page (default 25, at most 100) and answer data, page, per_page, total and has_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
curl "https://klibon.com/api/v1/merchant/programs/PROGRAM_ID/stats?range=30d&tz=Europe/Paris" \
  -H "Authorization: Bearer klbm_your_key"
200
{
  "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
curl "https://klibon.com/api/v1/merchant/programs/PROGRAM_ID/affiliates?status=approved&per_page=50" \
  -H "Authorization: Bearer klbm_your_key"
200
{
  "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
}

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.

destination_urlurl · required
The page the link lands on. It must be on your product's domain or one of its subdomains.
labelstring, 60 max · optional
A name for the campaign, shown to the affiliate beside the link.
slugstring · optional
The end of the address (/r/<slug>), 3 to 40 lower-case letters, digits and single dashes. Leave it out and Klibon picks a free one. A slug already taken answers 409.
curl
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"
  }'
201
{
  "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.

  • 401 missing_key — No Authorization header.
  • 401 product_key — A Conversions API key (klb_…) was sent. This API takes an account key (klbm_…).
  • 401 invalid_key — The key is unknown or revoked.
  • 402 plan_required — The account is not on Scale. The key is kept and works again once it is.
  • 403 insufficient_scope — The key lacks the permission this endpoint needs.
  • 429 rate_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.
402
{
  "statusCode": 402,
  "statusMessage": "The merchant API is part of the Scale plan. …",
  "data": { "code": "plan_required" }
}