Loading
A client eCommerce platform built around Shopify, where the storefront is only part of the requirement. The commercial model depends on an affiliate network with multi-level commissions, which means attribution, commission calculation, partner visibility and payouts all need to be correct and auditable. That is the part Shopify does not do, and the part where a spreadsheet stops being viable. The platform is in active development.
Affiliate programmes fail on trust. A partner who cannot see what they earned, or who is paid an amount they cannot reconcile, stops promoting. Doing multi-level commission calculation by hand means month-end reconstruction from links and memory, no clear audit trail, and disputes that cannot be settled with evidence. Add returns - which should claw back commission already accrued - and manual calculation becomes untenable.
The brief, before any technology was chosen.
Described in layers, because that is how the design decisions actually separate.
Shopify owns catalogue, cart, checkout and payment. Deliberately not rebuilt - it is the part that already works and is PCI-handled.
Referral codes and links resolve to a partner at order creation and are persisted on the order. Attribution is captured at the event rather than inferred later, because later is when it becomes guesswork.
A rules engine walks the partner tree and computes per-level commission as ledger entries. Every entry references the order and the rule version that produced it, so a historical payout can still be explained after rates change.
Append-only entries with states - accrued, approved, paid, reversed. Nothing is edited in place, which is what makes the ledger auditable and disputes resolvable.
Postgres via Supabase with row-level security, so a partner can only read their own tree and their own earnings.
A partner dashboard for referrals and earnings, and an admin console for approvals, rate configuration, payout runs and reconciliation.
Catalogue, order and fulfilment synchronisation over the Admin API and webhooks.
Code and link resolution persisted on the order at creation.
Configurable per-level rates computed across the partner tree.
Referrals, conversions, earnings by state and payout history.
Append-only entries with a traceable path from order to payment.
Returns and cancellations reverse the corresponding commission entries.
Partner approval, rate configuration, payout runs and reconciliation reports.
Automated confirmation and shipping updates on WhatsApp and email.
The problems worth writing down, and how each one was handled.
Customers click a partner link, leave, and return directly days later. We persist attribution server-side against the resolved code with a defined window and a documented last-touch rule, rather than depending on a cookie that may not survive the journey.
Ledger entries reference the rule version used. Changing a rate never rewrites history, so a payout made last quarter can still be explained.
Reversal entries rather than deletions. The ledger shows the accrual, the payment and the clawback as separate facts, which is what makes a dispute settleable.
Validation at partner registration and at attribution time, plus cycle detection when walking the tree so commission calculation cannot loop.
Scheduled jobs compare Shopify order totals against ledger accruals and flag divergence, because an unreconciled ledger is a liability rather than a record.
Sequence matters. Each step was chosen because it de-risked the next one.
Attribution accuracy
Pending measurement
Share of partner-referred orders correctly attributed on audit
Ledger reconciliation variance
Pending measurement
Difference between store order totals and ledger accruals per cycle
Manual effort per payout cycle
Pending measurement
Admin hours per payout run, baselined against the spreadsheet process
Commission dispute rate
Pending measurement
Disputes raised per hundred payouts
Apps cover single-level programmes well and we would recommend one for that. The multi-level tree, the clawback rules and the payout ledger this business model needs sit outside what the off-the-shelf options do, and bending an app into that shape is usually more fragile than building the commission layer properly.
The architecture transfers - webhook ingestion, attribution, a versioned commission engine, an append-only ledger. The commission rules themselves are always business-specific, so it is a reusable pattern rather than a reusable product.
Describe the system you have in mind. We will tell you what it takes, what we would do differently, and whether we are the right team for it.
