DEV Community: rutvik patel

5 Edge Cases That Break a Simple Referral Program

rutvik patel — Sat, 07 Nov 2026 08:01:46 +0000

A referral program looks like one line of logic: if someone signs up through a link, pay the person who shared it.

Then real money gets involved. We recently built one for our SaaS, with commissions paid on every customer payment for 12 months. Most of the work went into these five cases.

1. Two links, one customer: who gets the credit?

A visitor clicks one promoter's link on Monday and another promoter's link on Thursday. You have to choose, and the rule has to be simple enough to explain to both of them.

We chose first touch. The first valid code is kept, and later ones are ignored:

if ($code === null || $this->current($request) !== null) {
    return; // invalid code, or this visitor already has one
}

The code goes in the session and a first-party cookie for 30 days. The cookie holds only the code. It is cleared once the account is created, and from then on the link is stored on the account itself.

We also ignore the link for signed-in users, so an existing customer can't be claimed by someone who sends them a link later.

2. People will refer themselves

If a referral pays commission and also gives a discount, someone will try signing up through their own link with a second email address.

So we compare the mobile number and the real inbox. Gmail ignores dots and everything after a +, so these are all the same person:

private static function inbox(?string $email): string
{
    $email = strtolower(trim((string) $email));
    [$local, $domain] = explode('@', $email, 2);
    $local = explode('+', $local, 2)[0];

    if (in_array($domain, ['gmail.com', 'googlemail.com'], true)) {
        $local = str_replace('.', '', $local);
        $domain = 'gmail.com';
    }

    return $local . '@' . $domain;
}

This won't stop someone with a different phone and a different inbox. For that, we flag unusual patterns for a person to review. Nothing is blocked automatically, because a false accusation is expensive too.

3. One payment can arrive more than once

A payment can be confirmed by the browser, by a webhook and by a reconciliation job. If each one creates a commission, you pay three times.

Checking first isn't enough, because two requests can pass the check together. So the database has the final say:

Schema::create('promoter_commissions', function (Blueprint $table) {
    // ...
    $table->foreignId('payment_id')->unique();
});

When two requests race, the second insert fails. We catch that and return the row that already exists.

4. Customers get refunds after you've counted the commission

If you pay commission immediately and the customer gets a refund the next week, you've lost that money.

Our refund window is 30 days, so a commission waits the same 30 days:

pending (30 days) -> approved -> paid
        \                \
         -----------------> reversed

If a payment stops being successful, an unpaid commission is reversed. A commission that was already paid stays on the record and is settled by hand.

5. Your revenue isn't the amount the customer paid

Our Indian prices include 18% GST, and that tax isn't our income. If we paid commission on the full amount, we'd pay it on money we pass to the government.

Say a customer pays ₹1,180:

Item	Amount
Customer pays	₹1,180
GST at 18%	₹180
Base for commission	₹1,000
Commission at 20%	₹200

We save the tax split on each payment when it's created. That way, a later change to the tax rate can't change an old commission.

What we left out

We send payouts by hand over UPI or bank transfer, and record the transaction reference. Automating this can wait until the volume justifies it, and a person looking at each payout is also one more fraud check.

If you've built something like this, which edge case surprised you most? I'd like to hear about it in the comments.

Disclosure: this is the system behind the RSFlowHub promoter program, which I work on. It pays 20% of customer payments for 12 months. The code above is simplified from ours. I used an AI assistant to draft this post, and checked the details against our code.

How We Keep a Chat Widget to 4 KB on Every Page Load

rutvik patel — Sat, 07 Nov 2026 07:53:48 +0000

Most visitors never open a chat widget, but every one of them downloads it.

That was the problem we wanted to avoid when building an embeddable chat widget. Customers paste one script tag on their site, so our code runs on pages we don't control, on connections we can't predict. It has to be small, it can't break the host page, and it has to work under a strict Content-Security-Policy.

Here is what we ended up with:

File	Gzipped	When it loads
Loader	about 4 KB	Every page view
Full chat	about 20 KB	First time it's needed

Split the widget in two

The script tag only loads the loader. It does three things:

Fetches the chatbot's public settings
Draws the launcher button
Waits

The chat UI, message rendering and everything else live in a second file. If nobody opens the chat, that file is never downloaded.

Start the download on intent, not on click

Waiting for a click means the visitor stares at a button while a file downloads. So we start earlier, as soon as they show interest:

const preload = () => loadChat().catch(() => { /* retried on click */ });

['pointerenter', 'focus', 'touchstart'].forEach((event) =>
  button.addEventListener(event, preload, { once: true, passive: true })
);

button.addEventListener('click', open);

Keyboard users get the same head start through focus. On click, the button switches to its open state immediately, so there is feedback while the file finishes loading.

Don't cache a failed load forever

Keeping one shared promise stops the file loading twice. But if that promise rejects and you keep it, one network blip breaks the chat until the next page load. So we clear it on failure:

let chatPromise = null;

function loadChat() {
  if (window.__CHAT__) return Promise.resolve(window.__CHAT__);
  if (chatPromise) return chatPromise;

  chatPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.src = chatUrl;
    script.async = true;
    script.onload = () => resolve(window.__CHAT__);
    script.onerror = () => reject(new Error('chat failed to load'));
    document.head.appendChild(script);
  }).catch((error) => {
    chatPromise = null; // the next click tries again
    throw error;
  });

  return chatPromise;
}

Give the page a working API before the chat exists

Site owners want to call things like Chat.open() from their own buttons, and they shouldn't have to know whether the chat has loaded. So the loader exposes a small facade with the same methods. Each one waits for the real chat, then forwards the call:

window.Chat = {
  open: () => ensureStarted().then((chat) => chat.open()),
  toggle: (state) => ensureStarted().then((chat) => chat.toggle(state)),
  // ...
};

Once the chat has started, it replaces the facade as the public object.

Make the swap invisible

The placeholder button and the real one use the same markup and the same CSS file, which the build includes in both bundles. When the chat takes over, nothing jumps.

The catch is that two files now have to agree on that markup, so a test checks they stay in step.

Shadow DOM is not enough on its own

We render inside a shadow root so the host page's CSS can't reach our elements. But inherited properties still cross the boundary, so we start with this:

:host {
  all: initial;
}

That still wasn't enough. A rule like this on the host page also matches our custom element, and outer styles beat :host:

* {
  letter-spacing: 4px !important;
}

So the first element inside the shadow root resets everything again:

.launcher-wrapper {
  all: initial;
  /* then set position, fonts and so on */
}

Work under a strict CSP

Plenty of sites block inline styles and inline handlers, so templates can't use style="" or onclick. For the stylesheet, we use constructable stylesheets and fall back to a <style> tag:

const sheet = new CSSStyleSheet();
sheet.replaceSync(css);
shadowRoot.adoptedStyleSheets = [sheet];

Text from the owner's settings only ever goes in through textContent, never innerHTML.

Protect the budget with a test

Small bundles rarely stay small by accident. One careless import and the loader is suddenly carrying the whole chat. So a test fails if the loader goes over 16 KB raw or 6 KB gzipped.

The trade-offs

This setup has real costs:

A very fast click can still wait. On a slow connection, the chat takes a moment to appear.
Every page view makes one settings request. We set a 4 second timeout and fall back to the last copy in localStorage.
Some settings skip the lazy path. If a chat opens automatically, it has to load right away.
Old and new files can meet. A cached loader can talk to a newer chat file for up to an hour, so the chat's methods have to stay backward compatible within a version.

If you have shipped a third-party embed, what caught you out on real customer sites? I'd like to hear about it in the comments.

Disclosure: I work on RSFlowHub, and this is our chat widget. The code above is simplified from it. I used an AI assistant to draft this post, and checked the numbers and behaviour against our code.