Affiliates Architecture & Specs
Built on an immutable financial ledger with native database bindings to Commerce and Billing.
Performance Metrics
Tracking Latency
<5ms (in-transaction)
Refund Clawback Sync
Instant (Native Hook)
Ledger Integrity
Append-only Immutable
1. Native Tracking Integration
Unlike third-party systems that rely on asynchronous webhooks or fragile browser cookies, Aeion Affiliates is evaluated directly within the same checkout transaction as the order itself. Because Affiliates and Commerce share the same database, there is no webhook to miss, no sync window to drift, and no second system to reconcile. - Deterministic Promo Codes: The system reads the affiliate code directly from the validated order — the primary, most reliable attribution path, immune to cookie loss or ad-blockers. - First-Party Cookie Fallback: For organic traffic that arrives without a code, click attribution runs server-side via signed referral tokens. The token sets a first-party cookie and writes a server-side attribution record at click time, with a configurable attribution window. Conversion-side matching pairs customer email, transaction timestamp, and token reference — first-party data only, no third-party cookies. - Multi-Touch Attribution: When a conversion has multiple qualifying touchpoints across channels, attribution resolves which partner earns credit rather than silently awarding the last click. - Schema Validation: Strict, strongly-typed validation ensures all tracking data is well-formed before it's written to the ledger.
2. The Immutable Ledger
Every affiliate's commission history is a strict, append-only financial ledger — entries are never edited or deleted, only added. - Transaction Types: Commission, payout, and refund-reversal entries, each individually auditable. - Fraud Review: Commission entries post as pending and can be scored by an AI compliance agent (fraud risk 0–100) that recommends clear, manual review, payout hold, or affiliate suspension — a human keeps final say, this doesn't auto-lock the balance. - Atomic Balance Updates: An affiliate's total earned and current balance update atomically alongside each ledger entry — no drift between the summary and the underlying transactions.
3. Event-Driven Payout Surface
The whole lifecycle is event-driven, so each stage is observable and wireable without touching the ledger internals. Subscribe to any of these to extend the flow:
- affiliates.link.clicked — records the click and sets the first-party attribution cookie.
- affiliates.conversion.completed — calculates commission and appends the ledger entry.
- affiliates.order.refunded — clawback: appends the automatic reversal entry.
- affiliates.payout.requested — fires the moment an affiliate crosses their payout threshold; wire it into Stripe Connect, PayPal, an ACH batch export, or your own billing adapter to actually move money.
Because payout is an _event_ rather than a hardcoded rail, real-money transfers are always a deliberate, configured integration — never a silent side effect of a balance changing.
Frequently Asked Questions
Affiliates and Commerce share the same database, so commission logic reads the affiliate code directly off the validated order in the same transaction the order is written. There's no outbound webhook to fire, retry, or drop — the attribution is committed atomically with the sale.
A `Refund Event` triggers an automatic reversal entry in the affiliate's immutable ledger — the original `commission` stays in place (nothing is edited or deleted), and a matching negative `refund_reversal` entry is appended. The affiliate's balance updates atomically. No manual adjustment, no month-end reconciliation.
Every commission, payout, and reversal is an individually auditable entry, so the balance is always reconstructable from history and can't silently drift from the underlying transactions. Append-only is what makes the ledger trustworthy for financial review and fraud investigation.
No — by design. Crossing a payout threshold appends a payout entry and emits `affiliates.payout.requested`. Actually transferring funds is a deliberate integration you wire to a rail (Stripe Connect, PayPal, ACH batch export, or your own billing adapter). Real-money transfer is never a silent side effect of a balance change.
Each program's commission type — percentage or fixed amount — is applied per order server-side, so bounty amounts can't be manipulated from the client. Pending commissions can additionally be scored by an AI compliance agent (fraud risk 0–100) that recommends clear, review, hold, or suspend — but a human always keeps final say.