Referral program

Referrals turn happy customers into a sales channel. A member shares a personal code; their friend gets a welcome discount at sign-up; the member earns points once the friend actually buys. Every step is automatic, and a fraud layer keeps it honest.

Turn it on

Open Customers → Loyalty → Settings → Engagement & growth → Referral program and configure:

The program only records referrals while it is Active and Referral program is switched on. Referrer bonus points is 0 or more; Friend's welcome reward reads No reward until you pick one (create the reward in the Rewards tab first); Minimum qualifying order is 0 or more, in your store currency.

The row's live summary shows the whole configuration at a glance, for example "100 points to referrer · 10% off · cap 10/mo".

How a referral flows

1. The member gets a share code, a personal REF-XXXXXXXX code. The hosted loyalty widget and stores scaffolded with npx create-brainerce-store show it automatically, with a copyable share link, on the member's loyalty panel. A custom storefront needs its developer to render it (see Storefront requirement below).
2. The friend lands on your storefront via the shared link. The storefront can greet them by the referrer's first name, with "Rina sent you a gift: 10% off your first order", before they even sign up.
3. The friend registers with the code. Their welcome coupon is minted instantly and works at checkout across your sales channels. It is locked to that friend, so passing the code on to somebody else does nothing. It can be used once, and it never expires: no end date is set and there is no field for you to add one, so an unclaimed welcome discount stays redeemable indefinitely. Set Minimum order on the welcome reward if you need to bound what it can eventually cost you.
4. The friend places their first qualifying order. The referrer's bonus points are granted and held as pending for the program's Pending window (Settings → Advanced, not your return policy), exactly like purchase points.
5. If that order is cancelled or refunded, the referral is rejected and the referrer's bonus is taken back automatically.

Each customer can be referred once, ever, so repeat sign-ups with new codes don't earn anyone anything.

The Referrals tab

Customers → Loyalty → Referrals opens with a funnel (share codes issued → signed up → first order placed → flagged for review) that answers "is this working?" before you look at any row.

Below it, every referral with its status:

The status filter also lists Expired, but nothing in Brainerce sets a referral to Expired today, so that filter stays empty. Use the status filter above the table to look at one status, or switch on Flagged only to see just the referrals marked Review for a possible fraud signal. The columns are Referrer, Referred customer, Status, Date and Actions. A referral that is still Pending never expires on its own: there is no time limit for the friend to place the first order.

Fraud protection

Referral programs attract abuse, so several checks run silently on every sign-up:

• Disposable email addresses (mailinator-style throwaways) → the referral is rejected automatically, with the reason recorded. The friend's account is still created; only the referral is void.
• Email aliases of the referrer (e.g. [email protected] referring [email protected]) → rejected automatically.
• Same network address as the referrer → the referral is flagged for review, not blocked, because a shared household Wi-Fi is legitimate. Flagged referrals show a Review badge and complete normally unless you intervene.
• Monthly cap → once a referrer is over the cap, further referrals are recorded as Rejected so you can see them in the Referrals tab, but nobody is paid: no points for the referrer and no welcome coupon for the friend.

For anything the rules didn't catch, every referral row has a Reject button (it asks you to confirm, with an optional Reason such as "suspected self-referral" that is kept on the row): it voids the referral and reverses the referrer's points if they were already granted, even confirmed ones.

Friends who sign up with Google (social login)

A friend who arrives on a referral link and creates their account with Sign in with Google counts as a referral too: they get the same welcome coupon, go through the same fraud checks, and the referrer earns the same reward as with a regular email and password sign-up.

For this to work the storefront has to pass the referral code into the Google sign-in step. The default npx create-brainerce-store template does this from the version that added it. A custom-built storefront, or a store scaffolded before that version, needs its developer to pass referralCode when it starts the Google sign-in (see the integration guide). Until then, friends who sign up with Google join the program and get their sign-up points, but no referral is recorded and the referrer gets nothing.

What it does not do:

• An existing customer signing in with Google never becomes a referral, even if they clicked a friend's link first. Only a new account counts.
• Earlier Google sign-ups are not credited after the fact. A friend who signed up with Google before the storefront passed the code has no referral row, and there is no way to attach one later.

Storefront requirement

The referral landing greeting (e.g. "Rina sent you a gift") is rendered by your storefront using the loyalty SDK on every storefront, including the default npx create-brainerce-store template. Sign-up just passes the code along.

The share-code surface (where a member finds their own code to send out) is shown automatically by the hosted loyalty widget and by the default npx create-brainerce-store template. Only a custom-built storefront needs its developer to add it: render referralCode from getLoyaltyStatus() and build a link around it (https://your-store.com/?ref=<code>). Send your developer to the integration guide. It's a small task with copy-paste snippets.