ReferralCandy

Promptfree, for everyone, and the only version there is

Copy the prompt for Claude CodeCopy the prompt for CodexCopy the prompt for Cursor

Copy

Build me a referral programme that replaces ReferralCandy — and know why this is ALMOST.

Tracking a referral is straightforward. **Fraud detection is not**, and it is the whole reason this costs money. A referral programme with no defences becomes a self-referral machine within weeks: one person, several addresses, rewards for orders that are then refunded. Getting that wrong costs cash rather than credibility.

STACK
- Node 20+ with Fastify, server-rendered HTML
- SQLite through better-sqlite3, WAL mode
- Your payment or commerce platform's webhooks as the source of truth for orders
- Caddy in front

THE DATA MODEL
- programmes: id, name, advocate_reward_json, friend_reward_json, qualifying_rules_json, hold_days, max_rewards_per_advocate, is_active
- advocates: id, customer_external_id, email_hash, code, share_token, status, created_at, blocked_at, block_reason
- referrals: id, advocate_id, friend_email_hash, click_id, status, converted_at, order_external_id, order_amount_cents, matured_at, voided_at, void_reason
- clicks: id, advocate_id, at, ip_hash, user_agent_bucket, referrer_host, country, device, bot, session_hash
- rewards: id, referral_id, party, kind, value_cents, code, status, issued_at, redeemed_at, revoked_at, revoke_reason
- Everything append-only. A reward is never edited — it is revoked and a new one written, with a reason

FRAUD, WHICH IS THE ACTUAL PRODUCT
- **Self-referral**: the same person on both ends. Match on email hash, address hash, payment fingerprint where the processor gives one, delivery address, and device. Any match blocks the reward and flags for review
- **Address tricks**: a plus-address or dots in the local part are the same mailbox at most providers. Normalise before hashing, and treat disposable domains as suspect
- **Refund harvesting**: a reward issued on an order that is refunded a week later. That is what the hold period is for
- **Velocity**: an advocate producing many referrals in a short window, or referrals whose orders all come from one address range. Flag rather than block, and review
- **Coupon stacking**: a referral reward combined with a discount that makes the order unprofitable. Qualifying rules must be able to exclude discounted orders
- Every check produces a score and a reason. Flag for review rather than blocking silently — a real customer whose reward vanished with no explanation is a support problem and a public complaint
- Every decision recorded, including the ones a human overrode

WHEN A REWARD IS EARNED
- Only from a completed, paid order, never from a signup, a trial or a cart
- A hold period before it matures — long enough to cover your refund window — during which a refund voids it
- A refund after issuing revokes the reward, and if it has been redeemed, that is a loss you record rather than claw back. Set the hold period so that is rare
- Qualifying rules: a minimum order value, first order only, excluded products, excluded discount codes. All configurable per programme
- A cap per advocate, which is the simplest and most effective defence there is

ATTRIBUTION
- A share link with a token, setting a first-party cookie on your own domain and recording a click
- On conversion the token travels from the browser into the order and is stored against it at the processor. From that moment attribution lives on the order, not in a cookie
- A window, stated in the terms, and stated the same way in the advocate's own dashboard
- Bots and link-preview fetchers flagged and never attributed

THE ADVOCATE'S VIEW
- Their link, their clicks, their referrals with status, and their rewards with why each is pending, mature, paid or void
- Numbers that agree with yours because they come from the same rows
- The terms with a version, and the version they accepted recorded
- Sharing by email, message and social, with a pre-written line they can edit

REWARDS
- A discount code, store credit, or cash. A code must be single-use and tied to the referral, or it will end up on a coupon site within a day
- Issued automatically on maturity, or held for approval above a threshold
- The friend's reward is what makes the share worth sending; the advocate's is what makes it get sent. Both matter

OPERATIONS
- .env: DATABASE_PATH, BASE_URL, HASH_SALT, SESSION_SECRET, PLATFORM_WEBHOOK_SECRET, SMTP_URL
- Migrations on boot, each once; reconcile nightly against the commerce platform
- Nightly backup off the machine
- Health endpoint reporting webhook lag and the flagged queue

WHAT MATTERS MOST
The hold period and self-referral matching. Build those before the sharing page looks good, then simulate one person with four addresses and one order refunded on day twenty.