Skip to main content
Using an LLM to implement this? Every section in this guide is written to be unambiguous for automated implementation. Each snippet is labelled with the exact page or event trigger it belongs to. You can paste this entire page into your AI assistant and ask it to find the right places in your codebase.

How Affixo tracking works

Affixo tracks three events in an affiliate’s journey: All three share a single attribution chain. The snippet records the click on Affixo’s side and remembers who the visitor is; track('signup'), the Stripe integration and your server-side sale calls carry that visitor forward, and Affixo matches each event back to the right affiliate from their click history automatically.

Step 1: Add the snippet to every page

Where: The <head> of every page on your site (layout file, base template, _document.js, etc.). What it does: Detects when a visitor arrives via an affiliate link (?ref=, ?via=, ?fpr=, and others), records the click and remembers the visitor in their browser, and fires a page-view hit so you can see which domains are active.
The snippet does not set a cookie on your domain; it can’t, because it’s served from go.affixo.dev. Visitor identity is kept in your visitors’ browser storage instead, and read back with Affixo.getVisitorId(). Practical consequence: Safari and every iOS browser clear that storage after about 7 days of no return visit, so a click-based referral older than a week may fall back to weaker matching (device fingerprint, then IP) on those browsers. Coupon, manual-code, subscription-renewal and email-match attribution are unaffected; see Attribution.
Replace YOUR_PUBLIC_KEY with the key shown in Settings → Tracking & install. It starts with pk_ followed by 32 letters and digits.
The ?w= key is what identifies your workspace. Without it the snippet fires hits to the wrong account (or none at all). Always copy it from your dashboard; don’t type it manually.

Framework examples

Verify it works: Go to Settings → Tracking & install, scroll to the live test, enter your site URL, and click Run test. A confirmed hit means step 1 is complete.

Step 2: Track signups (leads)

Where: Your signup confirmation or thank-you page, the page a user lands on after they successfully sign up or opt in. Do not put this on the form page itself; it must fire only after the account is created. What it does: Records the referred visitor as a lead. This tells Affixo “this affiliate sent us a signup.” No commission is earned at this stage; leads are a count metric that proves attribution is working before money changes hands.
Affixo only exists once the Step 1 snippet has loaded, and that snippet loads async, so an inline call placed right after it can run first and fail with Affixo is not defined. Wrapping the call in window.addEventListener('load', ...) waits for it. The thank-you page must include the <head> snippet too.
Pass the user’s email or ID so Affixo can deduplicate signups and show who the lead is. An email sent from the browser can link the lead to a payment made within 24 hours (a checkout on the same visit). For a purchase made later, carry the visitor id into Stripe Checkout or book the signup from your server, where the email counts for a full year:

Framework examples


Step 3: Track sales (customers)

Using Stripe? Sales come from Stripe, and you must wire the visitor id into Checkout (below). If you’ve connected Stripe to Affixo (Settings → Payments & products), sales are recorded automatically and server-side, with the exact amount paid after discounts, coupon-code attribution, and automatic refund/chargeback reversal. A browser track('sale') on top is optional and never books money: on a live site it is recorded as an attributed lead with no amount, which tags the buyer’s email so the Stripe charge can be matched to the affiliate. It can’t double-count the sale. But for a cookie-tracked referral (the visitor clicked an affiliate link, no coupon code), Affixo can only connect the payment back to the affiliate if your Checkout Session carries the visitor id; see Stripe: pass the visitor id immediately below. Without Stripe, sales are booked from your server; see No Stripe: book sales from your server.

Stripe: pass the visitor id [#stripe-pass-the-visitor-id]

Without this, a first-touch cookie referral through Stripe cannot be attributed; the sale is recorded but earns the affiliate nothing. (Coupon-code and returning-subscriber attribution still work without it; this is specifically about link/cookie clicks.)
When you create the Stripe Checkout Session, set the Affixo visitor id on it. Affixo reads it from client_reference_id or metadata.sa_visitor_id; either works. Read the id on the page with Affixo.getVisitorId() and hand it to your backend:
customer_creation: 'always' is payment-mode only. Stripe rejects it in subscription mode, which always creates a Customer anyway. Its default, if_required, means a one-off purchase mints no Customer at all: the sale still attributes and pays commission normally, but the referral records no UID, so a repeat purchase by the same buyer can’t be tied back to the same Stripe identity. It has to be set when the session is created. Once the checkout completes with no Customer, there is nothing to look up or backfill.
For subscriptions, the subscription_data.metadata.sa_visitor_id line is what lets renewal invoices attribute; a renewal invoice carries no client_reference_id of its own. One-off payments don’t need it.
Already using another affiliate tool (e.g. FirstPromoter) that sets client_reference_id to its id? Put the Affixo id in metadata.sa_visitor_id instead. Affixo prefers a metadata match over a foreign client_reference_id.

No Stripe: book sales from your server [#no-stripe-book-sales-from-your-server]

Want a guided path with recipes for PayPal, Square, Paddle, Lemon Squeezy and WooCommerce? See Connect any payment processor. This section is the reference.
A sale reported from the browser never books money. Affixo.track('sale', ...) on a live site is recorded as an attributed lead with amount 0, whatever amount you pass. Your public key ships in the page, so anyone could post a fake amount with it; only calls authenticated with a secret API key can create a payable sale. (In test mode a browser sale still books as a test sale, so the end-to-end check in Settings shows it.)
Set it up in the dashboard. Open Settings → Payments & products (or the Connect payments step of setup) and choose Another processor, or my own backend. Affixo then marks the setup step as done, lets you create a secret key for sales, shows the calls below ready to paste, and has a Send a test sale button. The test sale is marked as a test, so it is never paid and never counted. To check your own backend, add "is_test": true to a sale call: the dashboard shows the last sale call it received. You can switch back to Stripe until your first real sale. To pay commission on sales that don’t go through a connected Stripe account, record each sale from your backend once payment has actually succeeded:
  1. On your site, read the visitor id with Affixo.getVisitorId() and send it to your backend with the order (a hidden form field, or a field on your order record).
  2. When the payment is confirmed (your payment provider’s webhook, or your order-complete handler), call POST /v1/track/sale with a secret API key that has the track or write scope.
Send amount_cents rather than amount. It is converted using the currency’s own decimals, so 9900 is $99.00 in USD, 9900 is 9,900 yen in JPY (no decimals), and 9900 is 9.900 in KWD (three decimals). The older amount field takes major units (99.00) and still works, but don’t send both: that returns 400 amount_conflict.
Always set external_id to your order or invoice id. A retried webhook or a repeated call with the same external_id doesn’t create a second commission. It is required whenever you also send product_id, subscription_id, customer_id, billing_interval or amount_cents. A sale sent without it still books, but the response carries warning: "external_id_missing" and that form is deprecated, because a retry can book the sale twice.
One processor per account. A workspace takes its sales from Stripe or from this API, never both. If you use Stripe, use the native integration instead of this section.

Subscriptions and renewals

Send the same subscription_id on every payment of a subscription, along with billing_interval (one_time, month or year). Each renewal goes to the affiliate who referred the first payment, and earns whatever your commission rules pay for a renewal. Repeat purchases with the same customer_id work the same way. Send subscription_id and customer_id on the first call for each payment: a later call with the same external_id won’t add them to a sale that’s already booked.
The order Affixo checks follows your attribution settings, with the buyer’s email as a fallback for 365 days, the same as Stripe. Test and live ids never match each other. If a signup comes before the purchase, send a lead with the subscription_id or customer_id (and an external_id) so the later sales find their affiliate.

Products

Send product_id (your own id for the plan or item) to pay different rates per product. Affixo doesn’t know your products until you register them, and it never does that automatically. Until a product is registered, a sale for it earns the campaign’s default rate, or nothing if your products policy is off. Every sale is still tracked and allocated by default. Products appear on your Products page under Seen in sales as they’re sold, so send product_name with each sale to label them there. Add one to the catalogue to give it its own rate or switch it off. Register products on the Products page, or with the API:
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 connected to Stripe gets 409 stripe_connected, because its products sync from Stripe.

Refunds

Send the order’s external_id to POST /v1/track/refund. Add refunded_amount_cents (or refunded_amount in major units) with the total refunded so far on that order, not the amount of this one refund. Below the sale amount it is a partial refund and the commission shrinks in proportion. At or above the sale amount, or with no amount, the whole sale is refunded. A commission that was already paid becomes a clawback. 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.
The response is { "ok": true, "conversion_id": "...", "refund": "partial" }, or "full".

Chargebacks and won disputes

Call POST /v1/track/chargeback with the external_id when a dispute opens. The commission is reversed right away, with status chargeback. If you win, call POST /v1/track/dispute_won with the same external_id. A won dispute restores the commission to what it was before the chargeback, so an earlier partial refund still counts and a fully refunded order stays refunded. Calling it when there was no chargeback does nothing and returns restored: false. Chargebacks reported this way stay inside your workspace. They are never added to any shared buyer risk list. Create the API key under Settings → Developer & API. See Server-side tracking for every field and the refund call.

Server-side alternative

If you can’t rely on browser JavaScript for sales tracking (server-rendered checkouts, webhooks, payment processors that redirect off-site), use the server-side API instead. For Stripe, prefer the native integration (Settings → Payments & products); it captures sales automatically with the correct discounted amounts and needs no code. For Paddle, Lemon Squeezy, PayPal, Square or any other provider, follow Connect any payment processor. The API below is the same one it uses. See Server-side tracking for the full API reference. Quick example, record a sale from a Stripe webhook:

Summary checklist

Use this to verify your integration before going live:
  • The snippet (sa.js?w=YOUR_PUBLIC_KEY) is in <head> on every page
  • Affixo.track('signup') fires on the signup/thank-you page only, after account creation
  • Sales are tracked, via the connected Stripe integration, or from your backend with POST /v1/track/sale and a secret API key if there’s no connected Stripe account (a browser track('sale') books no money)
  • Stripe only: the Checkout Session sets client_reference_id (and, for subscriptions, subscription_data.metadata.sa_visitor_id) to Affixo.getVisitorId(); otherwise cookie/link referrals through Stripe don’t attribute
  • amount is in major units (99.00), or use amount_cents (9900) and never mix the two
  • external_id is set to your unique order/invoice ID to prevent duplicate commissions
  • The snippet live test in Settings → Tracking & install shows a confirmed hit
  • The end-to-end test in Settings → Tracking & install shows a lead and a sale both register

Common mistakes

Revenue allowances and continued tracking

Free includes $2,500 of lifetime affiliate-attributed sales revenue. Monthly paid allowances are $5,000 on Starter ($19/month), $15,000 on Growth ($49/month), and $50,000 on Scale ($99/month). Higher volume needs Custom. These figures measure attributed sales, not commissions. Paid usage resets per billing period; Free does not. Warnings appear at 80% and 90%. Exceeding the allowance immediately locks dashboard pages, management API and MCP reads and writes, configuration and payouts until a suitable upgrade. Tracking links, inbound events, attribution and commission calculations continue behind the scenes. Affiliates retain portal access. Billing, cancellation, support and portable core-data exports remain available to authorized team members. Existing uncapped grants and legacy subscriptions retain their terms.