Affiliates¶

Vectis ships a full affiliate program: application review, commission rules with multi-level precedence, append-only earnings ledger, and CSV-first payouts with a strategy hook for ACH providers.

The admin UI lives at Marketing → Affiliates and is split into three sub-pages:

Approvals¶

Affiliates apply from the storefront, uploading a W-9 or W-8 tax document and agreeing to the program terms. Applications land in Approvals in pending status for staff review.

Each row surfaces the affiliate's name, email, kind (individual or org), current status, tax-doc state, and approval date. Row actions:

• Approve (✓) — moves pending → active; the affiliate can start earning referrals.
• Open profile — jumps to the affiliate's detail view for commission overrides and member management.
• Review document — opens the uploaded W-9 / W-8 for verification.
• Suspend / Terminate (⛔) — stops new attributions immediately; prior ledger entries are preserved.

Status lifecycle:

graph LR
    A[pending] -->|approve| B[active]
    B -->|suspend| C[suspended]
    C -->|reinstate| B
    B -->|terminate| D[terminated]
    C -->|terminate| D

Commission Rules¶

Commissions are rate records with a scope and an effective window. When an order is attributed, the resolver walks a fixed precedence chain and uses the first rule that matches.

Resolution order¶

org-negotiated → individual default → product → category → channel → global

A per-affiliate default overrides the global default. A product rule overrides both when the order contains a matching product. Rules outside their effective_at .. expires_at window are skipped automatically.

Rule fields¶

Tiered rules¶

Tiered rules carry a tiers array (JSONB) of { min_qty, rate } or { min_total, rate } steps. The resolver picks the highest tier the attributed order satisfies.

Commission Ledger¶

Every attributed order writes rows to the append-only commission_ledger. Entries are never mutated — corrections ship as reversing entries. This guarantees that historical payouts reconcile exactly against the ledger.

A ledger row captures:

• affiliate_id, order_id, rule_id
• commission_amount (Decimal 14,2, in the affiliate org's base currency)
• status — pending, approved, paid, reversed
• attributable_amount — the basis amount the rate was applied to
• A snapshot of the rule (kind, rate, basis) at attribution time

Payouts¶

Payouts sweep approved ledger entries into period batches. The default rail is manual CSV — the ext_payout_csv strategy produces a manifest file that can be fed to an ACH tool.

Payout lifecycle¶

graph LR
    A[pending] --> B[approved]
    B --> C[processing]
    C --> D[paid]
    C --> E[failed]
    E --> B

Each payout row shows the affiliate, the covered period, status, gross, fees, net, paid date, and an external reference. Export CSV downloads the manifest for the current filter.

Default CSV rail¶

The manual rail writes the manifest to:

{data_dir}/vectis_payouts/{YYYY-MM}/manifest.csv

Columns are affiliate identifier, gross, fees, net, period, and a reference token. Swap in a provider extension (e.g. Tipalti, Trolley) to automate — see Extensions.

Attribution¶

Clicks on an affiliate referral code drop a ReferralClick row. When that visitor later completes a qualifying checkout, a ReferralAttribution row is written linking order → click → affiliate. The default attribution window is configurable per channel.

Multi-Factor Fraud Guard (Decided #179)¶

Attributions are evaluated against a multi-factor fraud guard before commission posts to the ledger. Signals scored:

1. Click → conversion latency — too-tight or too-stale relative to the program's expected curve
2. IP correlation — buyer IP matches the affiliate's last-known login or referrer IP
3. Account self-attribution — buyer's billing email matches an affiliate-managed account
4. Velocity — abnormal click density from a single source

When the guard fires, the commission enters the Affiliate Review Queue (admin /affiliates/approvals) with pending_review status. The affiliate sees the order on their dashboard but the commission is held until staff approves or denies. Signals and the decision are written to affiliate_commission_audit for appeal.

Per-channel thresholds for each signal live under Settings → Affiliates → Fraud Guard.

Affiliate Self-Service Portal¶

The storefront ships a /affiliates/* portal so affiliates can manage their own status:

When the AWIN integration is installed (carrier-style extension), the dashboard surfaces AWIN-sourced clicks and reports alongside Vectis-native attributions.

Developer Reference¶

Affiliate internals live in backend/vectis/modules/affiliate/:

• models.py — CommissionRule, AffiliateOrg, Affiliate, CommissionLedger, Payout
• services.py — AffiliateService, CommissionRuleService, CommissionService, PayoutService, AttributionService
• strategies.py — payout provider strategy interface (ext_payout_csv is the built-in)
• workflows.py — Temporal workflows for periodic payout sweeps

The GraphQL surface (mutations to approve/suspend, list ledger entries, generate payouts) is documented in the API Reference.