Skip to main content
The /v1/track/* endpoints let your backend report events without relying on the browser snippet. They require a workspace key with the track scope (or write, or *). Keys minted for an MCP connector are refused with 403: tracking creates and reverses money-bearing conversions, so it needs a REST API key. Taking payments outside Stripe? Connect any payment processor walks through it step by step. Referral codes match whatever their case. ?ref=Jane20, a ref of jane20 and a manual_code of JANE20 all find the same affiliate.

Click

ref is required; it identifies the referral link.
Returns the resolved visitor_id plus the identity match_method / match_confidence. Persist visitor_id so later conversions attribute cleanly.

Paused and archived campaigns

A click on a link that belongs to a paused or archived campaign, or to an affiliate you archived, still returns { "ok": true, ... }, so nothing on your side breaks. It just isn’t recorded: no click is logged and no one is credited for it. An affiliate’s own code is the exception. When it points at a paused campaign, Affixo credits another live campaign they belong to instead (your default campaign first, if they’re in it), so their code keeps working. Sales still come in while a campaign is paused, so you can see them, but what they earn depends on who the customer is:
  • A customer an affiliate first referred while the campaign was paused earns them nothing, and that sale stays unpaid even after you resume.
  • A customer they referred before the pause keeps paying out as usual. Renewals and later purchases from that customer earn exactly what they did before.
  • Anything sold after you resume earns normally.
See Campaigns for the full picture.

Lead & Sale

Report a signup (lead) or purchase (sale). Provide any identity signal you have (visitor_id, fingerprint, ref, or manual_code) and Affixo attributes the event using your workspace’s precedence rules.
amount is in major units, so 99.00 is $99. Send the buyer’s email and name when you have them. Both are optional. The name and email show on the affiliate’s Referrals list, so they can see who they referred, and the email lets Affixo match later payments from the same customer to the same affiliate.
sale and lead are idempotent on external_id, safe to retry. When no affiliate can be attributed you get { "ok": true, "attributed": false }.

Sale details

For merchants who take payment outside Stripe, a sale can carry more than an amount: external_id is required whenever a sale uses product_id, subscription_id, customer_id, billing_interval or amount_cents, or a lead uses subscription_id or customer_id. Without it you get 400 external_id_required. A sale that sends only the older fields and no external_id still books, with warning: "external_id_missing" in the response, but that form is deprecated because a retry can book it twice. A lead ignores money and product fields. It may carry subscription_id and customer_id, which later sales follow. A product_id that isn’t registered yet earns the campaign’s default rate, or nothing if your products policy is off. Register products on the Products page or with POST /v1/products. Registering a product doesn’t change what it earns, or what its past sales earned: it starts with the same setting as your other uncatalogued products. Turn it on or off, or give it its own rate, to change that. A workspace uses Stripe or this API for sales, never both. Choose it under Settings → Payments & products, where you can also create a key and send a test sale.

Refund

Refund a prior sale by its external_id. Add refunded_amount_cents (or refunded_amount in major units) with the total refunded so far on that order, not just this one refund. Below the sale amount, the refund is partial and the commission shrinks in proportion. At or above it, or with no amount, the whole sale is refunded. A commission that was already paid becomes a clawback.
Returns { "ok": true, "conversion_id": "...", "refund": "partial" } (or "full"). A refund that arrives before its sale is held and applied when the sale arrives. If the held amount covers the whole sale, the sale is fully refunded. A refund is always in the sale’s currency. You can leave currency out. If you send one that differs from the sale’s, you get 422 currency_mismatch and nothing is recorded. A refund with an amount that arrives before its sale needs currency, since there is no sale to take it from yet; without one you get 422 currency_required.

Chargebacks

Send POST /v1/track/chargeback with the external_id when a dispute opens. The commission is reversed straight away, with status chargeback.
If you win the dispute, send POST /v1/track/dispute_won with the same external_id. That restores the commission to what it was before the chargeback, so an earlier partial refund still counts and a fully refunded order stays refunded. It returns { "ok": true, "conversion_id": "...", "restored": true }. If there was no chargeback it does nothing and returns restored: false. Chargebacks reported through the API stay inside your workspace and never go to any shared buyer risk list. See the API Reference for full request/response schemas.