Conversions API

For everything Klibon has no connector for. You tell Klibon a payment happened; Klibon does the attribution and the commission. One endpoint, idempotent on your own event id.

What reaches Klibon

Only what you send. A sale needs a referral_code, a discount_code, or a customer Klibon already knows, so you can report just the payments an affiliate sent and the renewals of those customers. Payments nobody referred never leave your server. Read ?via= yourself as well (Without the script) and nothing from Klibon runs on your site either.

Endpoint

POST https://klibon.com/api/v1/conversions, with a JSON body and an API key in the Authorization header.

Authentication

Create a key on your program's Setup page. It starts with klb_ and is shown once — Klibon only stores a hash of it. Send it as a bearer token: Authorization: Bearer klb_….

A key belongs to a product, not to a program, so a leaked key can only ever write events for that one product. Creating a key also connects the generic processor to your program, which counts against your plan's processors-per-program limit — the same as adding Stripe.

Body

event_idstring · required
Your own id for this event. It is the idempotency key: send it twice and the second call changes nothing.
typesale | renewal | refund · required
What happened. A renewal is a payment from a customer already attributed to a referral.
amountinteger · required
What the customer paid after discounts, excluding tax, before your processor’s fees. Minor units, never a decimal: 2900 for $29.00, 1999 for €19.99. A currency without decimals sends the whole amount: 1999 for ¥1999. On a refund, the amount of that refund alone, on the same basis.
currencystring, 3 letters · required
ISO 4217, case insensitive. USD, EUR, JPY.
program_iduuid · sometimes
Only needed when the product this key belongs to runs more than one program. With a single program it is inferred.
referral_codestring · optional
The code you captured in the browser. The most direct way to attribute a sale. Needed on the first payment only: once Klibon knows the customer_id, renewals find the affiliate without it.
discount_codestring · optional
The coupon the customer applied. If it is one you assigned to an affiliate in Klibon, the sale is credited to them — with or without a referral code.
customer_idstring · optional
Your own customer id. This is what ties a later renewal or refund back to the sale that came first — send it on every event you can.
customer_emailstring · optional
Stored only as a salted hash, used to match a customer and to detect self-referral.
payment_idstring · on a refund
Your id for the payment. Required on a refund: it is how Klibon finds the commission to reverse. Send it on sales too, or the refund will have nothing to match.
customer_ipstring · optional
Used only for self-referral detection, and hashed before it is stored.
product_idstring · optional
Your own id for what was sold, so the rate you set for that product applies. Leave it out and the payment earns your program default.
itemsarray · optional
For a payment covering several products: [{ product_id, price_id?, amount?, quantity? }]. Each line earns its own rate and the results are summed into one commission. Amounts are minor units on the same basis as amount; omit them and the payment is split evenly.
subscription_idstring · optional
Your id for the subscription. It is what keeps two subscriptions from one customer running their own durations instead of sharing a counter.
testboolean · optional
true for a test. Only your test link can earn on it, it never reaches statements, stats or plan limits, and its ids are kept apart from real ones. A sale with your test link's code is a test even without it.

Two combinations are enforced:

  • A refund must carry payment_id.
  • A sale or renewal must carry at least one of referral_code, discount_code, customer_id or customer_email — something to attribute it by.

What to send as the amount

Klibon calculates the commission on the amount you send, exactly as sent. Send what the customer paid after discounts and excluding tax, before your processor's fees. That is the figure every built-in connector uses: an affiliate earns a share of your revenue rather than a share of somebody's VAT, and your processor's fees stay your cost, as they would without an affiliate.

A merchant of record such as Paddle or Lemon Squeezy collects and remits the tax for you, and the total it reports includes that tax: subtract it. On Paddle that is totals.total - totals.tax on the transaction, though the Paddle connector does this for you, with renewals and refunds included.

Renewals

Send the referral_code with the customer's first payment, together with your customer_id. That payment records which affiliate the customer belongs to. Every later payment from them needs only the same customer_id: Klibon finds the affiliate itself, so you never have to store the code on your side.

Sending the code again on a renewal is harmless. The customer stays with the affiliate their first payment recorded, even if the code names someone else. How long renewals keep earning is set by your program's commission duration, counted from the first payment that earned.

Klibon cannot see when the visit with ?via= happened, so a code sent on a first payment is credited as sent. If you read ?via= yourself, apply your program's cookie window when you look back through a customer's visits.

Example

curl
curl -X POST https://klibon.com/api/v1/conversions \
  -H "Authorization: Bearer klb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "inv_9f21c4",
    "type": "sale",
    "amount": 1999,
    "currency": "USD",
    "referral_code": "ada",
    "customer_id": "cus_8817",
    "customer_email": "[email protected]",
    "payment_id": "pay_44120"
  }'

A new event answers 201:

201
{
  "received": true,
  "duplicate": false,
  "event_id": "inv_9f21c4",
  "outcome": "commission"
}

The same event_id again answers 200 and does nothing. This is what makes a retry safe:

200
{
  "received": true,
  "duplicate": true,
  "event_id": "inv_9f21c4"
}

Outcomes

outcome says what the event turned into. It is informational — the event is stored either way, and none of these values mean you should send it again.

  • commission — A commission was written.
  • reversed — A refund reduced or reversed an existing commission.
  • duplicate_payment — This payment already reached Klibon through another event.
  • no_attribution — Nothing tied this payment to an affiliate. Most sales are simply not referred.
  • no_commission — Attributed, but nothing earned — a zero amount, terms past their duration, a product you set to earn nothing, or a test-mode payment on a live affiliate. The Events tab says which.
  • deferred — Stored, decided later: a refund that overtook its sale, or a program not activated yet (a test sale sent while the program is a draft answers this). Nothing is lost, and nothing needs re-sending.

When the outcome alone does not say why, the answer adds a reason code and a message in plain words. A test sale on a program that is still a draft answers deferred with program_not_active: it is stored, shows as Waiting in Sales → Event log, and is decided once you activate.

201
{
  "received": true,
  "duplicate": false,
  "event_id": "inv_9f21c4",
  "outcome": "deferred",
  "reason": "program_not_active",
  "message": "Stored. The program is not active yet, so nobody earns: the sale is decided when you activate it, within 90 days. …"
}

Warnings

When the referral_code you sent credits nobody on the program, the answer carries a warnings list. The event is stored anyway. The usual cause is sending the end of a tracked link (/r/…) instead of the code the link adds to your site's address as ?via=.

201
{
  "received": true,
  "duplicate": false,
  "event_id": "inv_9f21c4",
  "outcome": "deferred",
  "warnings": [
    {
      "code": "referral_code_not_credited",
      "message": "This referral_code is the end of a tracked link (/r/…), not a referral code. …"
    }
  ]
}

Refunds

Send the amount of that refund, not a running total. Klibon adds up the refunds it has already seen for the payment and reverses the commission in proportion. Two partial refunds of 1000 on a 2000 payment are two calls of 1000, not 1000 then 2000.

json
{
  "event_id": "rfnd_2210",
  "type": "refund",
  "amount": 1999,
  "currency": "USD",
  "payment_id": "pay_44120"
}

A refund that arrives before the sale it reverses is held and retried for three days rather than dropped. A refund on a commission already paid out becomes a negative line on the affiliate's next statement.

Testing

Your key works for tests and real sales alike: say which with "test": true. A test can only credit your test link, whose code is on the Setup page. It shows as Test in the Event log, and never reaches statements, stats or your plan's limits.

A test's customer_id, customer_email, subscription_id and payment_id are kept apart from real ones, so testing with a real customer's id never ties that customer to your test link. Send "test": true on every event of a test, renewals and refunds included: they carry no code to recognise them by. A sale with your test link's code is treated as a test even without it. A test commission cannot be deleted, but it is never paid.

Errors

  • 400 — the product runs several programs and the body named none.
  • 401 — the key is missing, unknown or revoked.
  • 404 — that program_id does not belong to this key's product.
  • 409 — the product has no active program.
  • 422 — the body did not validate, or one of the two required combinations above is missing. The message says which.

Every error is safe to retry with the same event_id once you have fixed the cause.

In code

node
async function reportConversion(body) {
  const response = await fetch('https://klibon.com/api/v1/conversions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.KLIBON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  })

  // Retry with the SAME event_id. A repeat is ignored; a call never made is a lost commission.
  if (!response.ok) {
    throw new Error(`Klibon ${response.status}: ${await response.text()}`)
  }

  return await response.json()
}

await reportConversion({
  event_id: invoice.id,
  type: 'sale',
  amount: invoice.total_cents - invoice.tax_cents, // after discounts, before tax and fees
  currency: invoice.currency,
  referral_code: referralCode,      // window.Klibon.referral(), carried through your checkout
  customer_id: customer.id,
  customer_email: customer.email,
  payment_id: payment.id
})

Call it from the same place you already fulfil an order — your processor's own webhook is usually the right spot, because it is the point where the money is confirmed. Get referral_code there by carrying window.Klibon.referral() through your checkout; see Install the script.