How We Built the Chiarelli Labs Affiliate Program

In our experience, referrals are one of the cheapest acquisition channels available, but only if they're easy to track and fair to pay out. Instead of subscribing to a third-party affiliate SaaS and wiring it up via webhook, we decided to build the program inside the lead pipeline we already had. This post documents the technical decisions behind Chiarelli Labs' public affiliate program.

Why build our own, instead of an affiliate SaaS

A third-party SaaS solves click tracking and payouts, but it sits outside the system that already knows which stage of the funnel each lead is in. Our pipeline (contact form, classification, discovery, proposal, execution, payment milestones) existed before the affiliate program. Building inside it means the same event that marks a milestone as paid is the same event that credits the commission.

Sign-up, link, and first-touch attribution

Sign-up is open at /afiliados: a 6-step onboarding that ends with accepting the terms, and accepting activates the referral link in the format chiarelli.dev/r/[code]. Visiting that link sets a cl_ref cookie: httpOnly, 60-day validity, first-touch model (the first referral to touch the lead counts, not the last). When that lead fills out the contact form, the same endpoint that receives the form reads the cookie, creates the referral record (affiliate_referrals), and blocks self-referral: if the lead's email matches the affiliate's, the record isn't created.

Automatic commission, manual payout

The commission is a percentage configurable per service track (we don't publish the exact rate). It's credited automatically the moment a project payment milestone is marked as paid, pro-rated (proportional to that specific milestone's value) and idempotent: marking the same milestone as paid twice doesn't duplicate the commission. The payout itself is manual, via PIX (Brazil's instant payment rail), tracked in a dedicated admin panel.

The dashboard protects the lead, not just the affiliate

Affiliate authentication is isolated from the rest of the site's auth: magic-link login, no password, with its own database tables and session cookie. The panel's most important detail, though, is what it doesn't show: the affiliate sees a pseudonym for the lead they referred, that lead's stage in the funnel, and the commission already earned from them, never the value of the closed contract. It's a product decision: the affiliate needs to know the referral is progressing and how much they'll earn, not what the end client paid.

Built in stages, with two bugfixes along the way

The program shipped in four stages: foundation (database schema and per-track commission configuration), activation (link sharing, click counting, a referral card with an AI-powered generator), conversion (automatic progress emails to the affiliate, mini success cases, a way for the affiliate to ask for help), and recruitment (a dedicated landing page, invites, a public sharing kit). After launch, two bugs surfaced and were fixed: downloading the referral card, which sometimes threw a 500 error, was replaced with a native link (<a download>); and the AI-generated card variants were reviewed and sanitized.

The program is live at /en/afiliados: open sign-up, a 6-step onboarding, and the link activates once you accept the terms. If you're already referring clients informally, you can formalize it there and track the return in your own dashboard.