Quickstart: Launch Your Partner Program

Aeion Affiliates doesn't track referral clicks or cookies against a ?ref= URL parameter. Instead, an affiliate's tracking code is a Discounts promo code with the affiliate's ID attached to its metadata. When a customer applies that code at checkout, the commission is attributed automatically.

Add an affiliate:

typescript const affiliate = await aeion.api.post("/v1/affiliates", { userId: "usr_acme_influencer", programId: program.id, code: "ACME25", status: "active", payoutMethod: "bank_transfer", // free-text — whatever your finance team uses payoutDetails: { accountRef: "acct_..." }, });

Link a matching discount code (Admin → Marketing → Discounts, or via the Discounts API) with:

• code: the same value as the affiliate's code (e.g., ACME25)
• metadata.affiliateId: the affiliate's record ID

Once linked, every order where a customer applies ACME25 at checkout fires a discounts.usage.recorded event; the Affiliates module looks up the promo code's metadata.affiliateId, calculates commission from the affiliate's program (commissionType / commissionValue against the order total), and writes a commission entry to that affiliate's ledger — no manual bookkeeping required.

Commission is computed automatically when a discount-linked order comes through:

• Percentage programs: commission = round(orderTotal × commissionValue / 100)
• Fixed-amount programs: commission = commissionValue (flat, regardless of order size)

Both the affiliate's running balance and totalEarned update immediately, and a commission row lands in affiliate_ledger.

Refunds claw back automatically. If the original order is refunded (commerce.order.refunded), the module finds the matching commission ledger entry and reverses it — no manual balance correction needed.

Payouts aren't wired to a payment processor automatically — payoutMethod is a free-text field you set per affiliate (bank transfer, PayPal, check, whatever your finance process uses), and payout requests land as pending ledger entries for your team to clear.

Affiliate-initiated request (from the Portal):

typescript await aeion.api.post("/v1/affiliates/portal/payout-request", { amount: 15000, // cents — guarded against requesting more than (balance − already-pending) });

This creates a pending payout entry in the ledger. It does not decrement the affiliate's balance yet — that happens when an admin clears the entry.

Admin-initiated payout (Admin → Affiliates → Dashboard):

typescript await aeion.api.post("/v1/affiliates/dashboard/payout", { affiliateId: affiliate.id, amount: 15000, method: "bank_transfer", });

Clearing a payout is a manual step in your own finance workflow — Aeion tracks the ledger; it doesn't move money.

Every affiliate can view their own record, ledger, and stats through a lightweight self-service Portal, scoped to their own userId — one affiliate can never see another's data.

typescript const { data } = await aeion.api.get("/v1/affiliates/portal/me"); // data.affiliate — their affiliate record // data.ledger — their last 100 ledger entries // data.stats — { totalEarned, pendingBalance, conversions, clearedCommissions }

From there they can call POST /v1/affiliates/portal/payout-request to request a payout against their available balance.

Three purpose-built AI agents ship with the module — each honors the platform's honest-fallback contract (if no AI provider is configured, they say so rather than fabricating a result):

• Compliance Agent (fraud detection) — auto-triggers on every new affiliate_ledger entry. Scores fraud risk and recommends an action (hold_payout, manual_review, suspend_affiliate, clear), writing to fraudScore + aiFlagged + aiFraudAnomalies so the admin's "Suspicious" segment reflects ground truth from day one.
• Recruiting Agent (partner-fit scoring) — operator-initiated. Scores how strong a fit a partner is and recommends a tier (bronze / silver / gold / vip) based on identity + earnings signal + program context. Writes to matchScore + aiSuggestedTier. This is a recommendation for you to review, not an automatic rate change.
• Affiliate Manager Agent (commission optimization) — operator-initiated. Analyzes a program's recent ledger performance and recommends a commission-rate adjustment (raise / lower / hold) with reasoning and expected impact. Requires your explicit approval before the new rate is applied — commission changes affect what partners get paid.

Admin → Affiliates → Dashboard surfaces:

• KPI stats — total + active affiliates, total earned, pending payouts (amount + count), commissions this month vs. last month (with trend %), active/total programs
• Top performers — ranked by earnings
• Recent ledger — latest commission / payout / adjustment entries across all affiliates
• Commissions trend — month-over-month commission volume