Record clicks and conversions directly from your backend.
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.
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.
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:
Field
What it does
amount_cents
Amount in minor units, converted by the currency’s decimals (0 for JPY, 3 for KWD). Recommended. Don’t send it together with amount.
product_id
Your own product id, for per-product rates.
subscription_id
Renewals with the same id go to the affiliate who referred the first payment.
customer_id
Repeat purchases with the same id go to the same affiliate.
billing_interval
one_time, month or year.
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Affixo","colors":{"primary":"#6366F1","light":"#818CF8","dark":"#4F46E5"},"navbar":{"primary":{"type":"button","label":"Dashboard","href":"https://app.affixo.dev"}},"footer":{"socials":{"website":"https://affixo.dev"}},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"affixo","hasAudioNarration":false,"actualSubdomain":"affixo","customDomains":["docs.affixo.dev"],"gitSource":{"type":"github","owner":"wizardsofsocial","repo":"affixo-app","deployBranch":"main","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6af71d8bc374640f8e24db1d","clientVersion":"0.0.4143","searchFilterCounts":[{"language":"default","tag":"API Reference","count":51},{"language":"default","tag":"Guides","count":35},{"language":"default","tag":"Vibe Coding","count":13},{"language":"default","tag":"Tracking","count":12},{"language":"default","tag":"Campaigns","count":12},{"language":"default","tag":"MCP Server","count":9},{"language":"default","tag":"Setup guides","count":7},{"language":"default","tag":"Products","count":7},{"language":"default","tag":"Webhooks","count":6},{"language":"default","tag":"Affiliates","count":5}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"tracking-overview","slug":"/tracking-overview","pageMetadata":{"title":"Server-side tracking","description":"Record clicks and conversions directly from your backend.","href":"/tracking-overview"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Record clicks and conversions directly from your backend.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Note,Table}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`The `,_jsx(_components.code,{children:`/v1/track/*`}),` endpoints let your backend report events without relying on\nthe browser snippet. They require a workspace key with the `,_jsx(_components.code,{children:`track`}),` scope (or\n`,_jsx(_components.code,{children:`write`}),`, or `,_jsx(_components.code,{children:`*`}),`). Keys minted for an MCP connector are refused with `,_jsx(_components.code,{children:`403`}),`:\ntracking creates and reverses money-bearing conversions, so it needs a REST\nAPI key.`]}),`\n`,_jsxs(_components.p,{children:[`Taking payments outside Stripe? `,_jsx(_components.a,{href:`/connect-any-processor`,children:`Connect any payment processor`}),` walks through it step by step.`]}),`\n`,_jsxs(_components.p,{children:[`Referral codes match whatever their case. `,_jsx(_components.code,{children:`?ref=Jane20`}),`, a `,_jsx(_components.code,{children:`ref`}),` of `,_jsx(_components.code,{children:`jane20`}),`\nand a `,_jsx(_components.code,{children:`manual_code`}),` of `,_jsx(_components.code,{children:`JANE20`}),` all find the same affiliate.`]}),`\n`,_jsx(Heading,{level:`2`,id:`click`,children:`Click`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`ref`}),` is required; it identifies the referral link.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://go.affixo.dev/v1/track/click`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer sa_live_your_key\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{ \"ref\": \"jane\", \"visitor_id\": \"v_abc\" }'`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Returns the resolved `,_jsx(_components.code,{children:`visitor_id`}),` plus the identity `,_jsx(_components.code,{children:`match_method`}),` /\n`,_jsx(_components.code,{children:`match_confidence`}),`. Persist `,_jsx(_components.code,{children:`visitor_id`}),` so later conversions attribute cleanly.`]}),`\n`,_jsx(Heading,{level:`3`,id:`paused-and-archived-campaigns`,children:`Paused and archived campaigns`}),`\n`,_jsxs(_components.p,{children:[`A click on a link that belongs to a paused or archived campaign, or to an\naffiliate you archived, still returns `,_jsx(_components.code,{children:`{ \"ok\": true, ... }`}),`, so nothing on your\nside breaks. It just isn’t recorded: no click is logged and no one is credited\nfor it.`]}),`\n`,_jsx(_components.p,{children:`An affiliate’s own code is the exception. When it points at a paused\ncampaign, Affixo credits another live campaign they belong to instead (your\ndefault campaign first, if they’re in it), so their code keeps working.`}),`\n`,_jsx(_components.p,{children:`Sales still come in while a campaign is paused, so you can see them, but\nwhat they earn depends on who the customer is:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`A customer an affiliate first referred `,_jsx(_components.strong,{children:`while the campaign was paused`}),`\nearns them nothing, and that sale stays unpaid even after you resume.`]}),`\n`,_jsxs(_components.li,{children:[`A customer they referred `,_jsx(_components.strong,{children:`before the pause`}),` keeps paying out as usual.\nRenewals and later purchases from that customer earn exactly what they did\nbefore.`]}),`\n`,_jsx(_components.li,{children:`Anything sold after you resume earns normally.`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`See `,_jsx(_components.a,{href:`/campaigns#pausing-a-campaign`,children:`Campaigns`}),` for the full picture.`]}),`\n`,_jsx(Heading,{level:`2`,id:`lead-\u0026-sale`,children:`Lead \u0026 Sale`}),`\n`,_jsxs(_components.p,{children:[`Report a signup (`,_jsx(_components.code,{children:`lead`}),`) or purchase (`,_jsx(_components.code,{children:`sale`}),`). Provide any identity signal you\nhave (`,_jsx(_components.code,{children:`visitor_id`}),`, `,_jsx(_components.code,{children:`fingerprint`}),`, `,_jsx(_components.code,{children:`ref`}),`, or `,_jsx(_components.code,{children:`manual_code`}),`) and Affixo\nattributes the event using your workspace’s precedence rules.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`11`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`11`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://go.affixo.dev/v1/track/sale`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer sa_live_your_key\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"visitor_id\": \"v_abc\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"external_id\": \"order_1234\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"amount\": 99.00,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"currency\": \"usd\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"email\": \"buyer@example.com\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"name\": \"Sam Buyer\"`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`amount`}),` is in major units, so `,_jsx(_components.code,{children:`99.00`}),` is $99.`]}),`\n`,_jsxs(_components.p,{children:[`Send the buyer’s `,_jsx(_components.code,{children:`email`}),` and `,_jsx(_components.code,{children:`name`}),` when you have them. Both are optional.\nThe name and email show on the affiliate’s Referrals list, so they can see who\nthey referred, and the email lets Affixo match later payments from the same\ncustomer to the same affiliate.`]}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`sale`}),` and `,_jsx(_components.code,{children:`lead`}),` are `,_jsxs(_components.strong,{children:[`idempotent on `,_jsx(_components.code,{children:`external_id`})]}),`, safe to retry. When no\naffiliate can be attributed you get `,_jsx(_components.code,{children:`{ \"ok\": true, \"attributed\": false }`}),`.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`sale-details`,children:`Sale details`}),`\n`,_jsx(_components.p,{children:`For merchants who take payment outside Stripe, a sale can carry more than an amount:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Field`}),_jsx(_components.th,{children:`What it does`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`amount_cents`})}),_jsxs(_components.td,{children:[`Amount in minor units, converted by the currency’s decimals (0 for JPY, 3 for KWD). Recommended. Don’t send it together with `,_jsx(_components.code,{children:`amount`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`product_id`})}),_jsx(_components.td,{children:`Your own product id, for per-product rates.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`subscription_id`})}),_jsx(_components.td,{children:`Renewals with the same id go to the affiliate who referred the first payment.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`customer_id`})}),_jsx(_components.td,{children:`Repeat purchases with the same id go to the same affiliate.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`billing_interval`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`one_time`}),`, `,_jsx(_components.code,{children:`month`}),` or `,_jsx(_components.code,{children:`year`}),`.`]})]})]})]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`external_id`}),` is required whenever a sale uses `,_jsx(_components.code,{children:`product_id`}),`, `,_jsx(_components.code,{children:`subscription_id`}),`, `,_jsx(_components.code,{children:`customer_id`}),`, `,_jsx(_components.code,{children:`billing_interval`}),` or `,_jsx(_components.code,{children:`amount_cents`}),`, or a lead uses `,_jsx(_components.code,{children:`subscription_id`}),` or `,_jsx(_components.code,{children:`customer_id`}),`. Without it you get `,_jsx(_components.code,{children:`400 external_id_required`}),`. A sale that sends only the older fields and no `,_jsx(_components.code,{children:`external_id`}),` still books, with `,_jsx(_components.code,{children:`warning: \"external_id_missing\"`}),` in the response, but that form is deprecated because a retry can book it twice.`]}),`\n`,_jsxs(_components.p,{children:[`A lead ignores money and product fields. It may carry `,_jsx(_components.code,{children:`subscription_id`}),` and `,_jsx(_components.code,{children:`customer_id`}),`, which later sales follow. A `,_jsx(_components.code,{children:`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 `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsxs(_components.p,{children:[`A workspace uses Stripe or this API for sales, never both. Choose it under `,_jsx(_components.strong,{children:`Settings → Payments \u0026 products`}),`, where you can also create a key and send a test sale.`]}),`\n`,_jsx(Heading,{level:`2`,id:`refund`,children:`Refund`}),`\n`,_jsxs(_components.p,{children:[`Refund a prior sale by its `,_jsx(_components.code,{children:`external_id`}),`. Add `,_jsx(_components.code,{children:`refunded_amount_cents`}),` (or `,_jsx(_components.code,{children:`refunded_amount`}),` in major units) with the `,_jsx(_components.strong,{children:`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.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://go.affixo.dev/v1/track/refund`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer sa_live_your_key\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{ \"external_id\": \"order_1234\", \"refunded_amount_cents\": 2500 }'`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Returns `,_jsx(_components.code,{children:`{ \"ok\": true, \"conversion_id\": \"...\", \"refund\": \"partial\" }`}),` (or `,_jsx(_components.code,{children:`\"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.`]}),`\n`,_jsxs(_components.p,{children:[`A refund is always in the sale’s currency. You can leave `,_jsx(_components.code,{children:`currency`}),` out. If you send one that differs from the sale’s, you get `,_jsx(_components.code,{children:`422 currency_mismatch`}),` and nothing is recorded. A refund with an amount that arrives before its sale needs `,_jsx(_components.code,{children:`currency`}),`, since there is no sale to take it from yet; without one you get `,_jsx(_components.code,{children:`422 currency_required`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`chargebacks`,children:`Chargebacks`}),`\n`,_jsxs(_components.p,{children:[`Send `,_jsx(_components.code,{children:`POST /v1/track/chargeback`}),` with the `,_jsx(_components.code,{children:`external_id`}),` when a dispute opens. The commission is reversed straight away, with status `,_jsx(_components.code,{children:`chargeback`}),`.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://go.affixo.dev/v1/track/chargeback`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer sa_live_your_key\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{ \"external_id\": \"order_1234\" }'`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`If you win the dispute, send `,_jsx(_components.code,{children:`POST /v1/track/dispute_won`}),` with the same `,_jsx(_components.code,{children:`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 `,_jsx(_components.code,{children:`{ \"ok\": true, \"conversion_id\": \"...\", \"restored\": true }`}),`. If there was no chargeback it does nothing and returns `,_jsx(_components.code,{children:`restored: false`}),`.`]}),`\n`,_jsx(_components.p,{children:`Chargebacks reported through the API stay inside your workspace and never go to any shared buyer risk list.`}),`\n`,_jsxs(_components.p,{children:[`See the `,_jsx(_components.a,{href:`/api-reference`,children:`API Reference`}),` for full request/response schemas.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Server-side tracking","description":"Record clicks and conversions directly from your backend.","href":"/tracking-overview"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Click","slug":"click","depth":2,"children":[{"title":"Paused and archived campaigns","slug":"paused-and-archived-campaigns","depth":3,"children":[]}]},{"title":"Lead \u0026 Sale","slug":"lead-\u0026-sale","depth":2,"children":[]},{"title":"Sale details","slug":"sale-details","depth":2,"children":[]},{"title":"Refund","slug":"refund","depth":2,"children":[]},{"title":"Chargebacks","slug":"chargebacks","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"affixo","siteName":"Affixo","title":"Server-side tracking - Affixo","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-13T14:24:15.737Z","originalFileLocation":"tracking-overview.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Record clicks and conversions directly from your backend.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Affixo\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/affixo/_generated/favicon/apple-touch-icon.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/affixo/_generated/favicon/favicon-32x32.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/affixo/_generated/favicon/favicon-16x16.png?v=3\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/affixo/_generated/favicon/favicon.ico?v=3\">\u003cmeta data-mint-head property=\"og:title\" content=\"Server-side tracking - Affixo\">\u003cmeta data-mint-head property=\"og:description\" content=\"Record clicks and conversions directly from your backend.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Affixo\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.affixo.dev/tracking-overview\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://affixo.mintlify.site/_mintlify/api/og/v2?division=Tracking\u0026amp;title=Server-side+tracking\u0026amp;description=Record+clicks+and+conversions+directly+from+your+backend.\u0026amp;theme=0a3a852175ddc8e5bfd2cfca\u0026amp;signature=aa45c9e90fd95981b70953da27b903835fcda87254405b3b07ba08cb83df2b05\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Server-side tracking - Affixo\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Record clicks and conversions directly from your backend.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://affixo.mintlify.site/_mintlify/api/og/v2?division=Tracking\u0026amp;title=Server-side+tracking\u0026amp;description=Record+clicks+and+conversions+directly+from+your+backend.\u0026amp;theme=0a3a852175ddc8e5bfd2cfca\u0026amp;signature=aa45c9e90fd95981b70953da27b903835fcda87254405b3b07ba08cb83df2b05\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"https://mintlify.s3.us-west-1.amazonaws.com/affixo/_generated/favicon/browserconfig.xml?v=3\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Affixo\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#6366F1\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.affixo.dev/tracking-overview\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/tracking-overview.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.affixo.dev/#organization\",\"name\":\"Affixo\",\"url\":\"https://docs.affixo.dev\"},{\"@type\":\"WebSite\",\"@id\":\"https://docs.affixo.dev#website\",\"name\":\"Affixo\",\"url\":\"https://docs.affixo.dev\",\"publisher\":{\"@id\":\"https://docs.affixo.dev/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.affixo.dev/tracking-overview#webpage\",\"url\":\"https://docs.affixo.dev/tracking-overview\",\"name\":\"Server-side tracking\",\"description\":\"Record clicks and conversions directly from your backend.\",\"dateModified\":\"2026-11-13T14:24:15.737Z\",\"isPartOf\":{\"@id\":\"https://docs.affixo.dev#website\"},\"breadcrumb\":{\"@id\":\"https://docs.affixo.dev/tracking-overview#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.affixo.dev/tracking-overview#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Tracking\",\"item\":\"https://docs.affixo.dev/integrate\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Server-side tracking\",\"item\":\"https://docs.affixo.dev/tracking-overview\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.affixo.dev/tracking-overview#article\",\"headline\":\"Server-side tracking\",\"name\":\"Server-side tracking\",\"description\":\"Record clicks and conversions directly from your backend.\",\"url\":\"https://docs.affixo.dev/tracking-overview\",\"mainEntityOfPage\":{\"@id\":\"https://docs.affixo.dev/tracking-overview#webpage\"},\"dateModified\":\"2026-11-13T14:24:15.737Z\",\"publisher\":{\"@id\":\"https://docs.affixo.dev/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.affixo.dev#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Affixo\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Affixo\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/tracking-overview.md","siteName":"Affixo","nav":{"global":null,"tabs":[{"tab":"Guides","groups":[{"group":"Get Started","pages":[{"title":"Introduction","href":"/introduction"},{"title":"Authentication","href":"/authentication"},{"title":"Errors and limits","href":"/errors-and-limits"}]},{"group":"Tracking","pages":[{"title":"Integrate Affixo tracking","href":"/integrate"},{"title":"Connect any payment processor","href":"/connect-any-processor"},{"title":"sa.js reference","description":"What the tracking snippet reads from the page, and the window.Affixo functions you can call.","href":"/sa-js"},{"title":"Server-side tracking","href":"/tracking-overview"},{"title":"How attribution works","description":"The precedence-ordered methods Affixo uses to credit a conversion to the right affiliate.","href":"/attribution"},{"title":"Attribution Recovery","href":"/attribution-recovery"}]},{"group":"Vibe Coding","pages":[{"title":"Vibe coding","href":"/vibe-coding"},{"title":"Lovable","href":"/vibe/lovable"},{"title":"Bolt","href":"/vibe/bolt"},{"title":"v0","href":"/vibe/v0"},{"title":"Replit","href":"/vibe/replit"},{"title":"Base44","href":"/vibe/base44"},{"title":"Cursor","href":"/vibe/cursor"},{"title":"Windsurf","href":"/vibe/windsurf"},{"title":"Claude Code","href":"/vibe/claude-code"},{"title":"Claude.ai","href":"/vibe/claude-web"},{"title":"Codex","href":"/vibe/codex"},{"title":"Gemini CLI","href":"/vibe/gemini-cli"},{"title":"VS Code Copilot","href":"/vibe/copilot"}]},{"group":"Programs","pages":[{"title":"Campaigns","href":"/campaigns"},{"title":"Moving referrals and correcting sales","href":"/moving-referrals"},{"title":"Sub-affiliates (two-tier programs)","href":"/sub-affiliates"}]},{"group":"Webhooks","pages":[{"title":"Webhooks","href":"/webhooks"}]},{"group":"MCP Server","pages":[{"title":"MCP Server","href":"/mcp-server"},{"title":"Example queries","href":"/mcp/examples"},{"group":"Setup guides","pages":[{"title":"Cursor","href":"/mcp/setup/cursor"},{"title":"VS Code","href":"/mcp/setup/vscode"},{"title":"Claude Code","href":"/mcp/setup/claude-code"},{"title":"Codex","href":"/mcp/setup/codex"},{"title":"Gemini CLI","href":"/mcp/setup/gemini"},{"title":"Claude","href":"/mcp/setup/claude"},{"title":"ChatGPT","href":"/mcp/setup/chatgpt"}]}]}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/affiliates/list-affiliates"}]}]},"basePath":"","title":"Server-side tracking - Affixo","buildId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","deploymentId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","dynamics":[],"chunks":[]}