Pattern: referral loop
Give-200, get-200 double-sided referral. Code generated server-side, share message pre-filled, attribution on conversion (not click), per-inviter cap, anti-fraud checks. Always-on, not campaign-bound.
Key takeaways
Quick read- Configure the referral program once. Server generates a unique code per participant.
- Pre-filled WhatsApp share doubles share rate vs free-text.
- Attribution fires on the converted action (signup, first purchase) not on click.
- Per-inviter cap (e.g. 25 successful referrals per quarter) protects the budget.
- Anti-fraud: same device, same payment method, disposable email patterns are blocked server-side.
Anatomy
What you are building
API
The referral program (structure, rewards, caps, fraud) is configured in the dashboard. Codes come from POST /api/v1/gamify/referrals/generate (or useReferral). Record a conversion with POST /api/v1/gamify/referrals/convert.
SDK
useReferral returns code, shareUrl, defaultMessage, history, and share().
User sees
Their unique code, a share button that opens WhatsApp/SMS with the message pre-filled, a list of converted invites with reward status.
Step 1: config
Configure the program, then generate codes
The referral program itself — structure (single or double sided), inviter/invitee rewards, caps, and fraud rules — is configured in the dashboard, not via a public API. Once it exists, your app works with two real endpoints: generate a participant’s code, and record a conversion.
# 1. Generate (or fetch) the inviter's referral code.
curl -X POST https://api.bricqs.co/api/v1/gamify/referrals/generate \
-H "X-API-Key: bq_live_..." \
-H "Content-Type: application/json" \
-d '{ "participant_id": "user_42", "campaign_id": "cmp_loyalty" }'
# 2. When the invitee converts (e.g. first purchase), record it.
curl -X POST https://api.bricqs.co/api/v1/gamify/referrals/convert \
-H "X-API-Key: bq_live_..." \
-H "Content-Type: application/json" \
-d '{ "referral_code": "USER42-A1B2", "referee_participant_id": "user_99" }'Reward issuance, caps, and fraud checks run inside conversion per the program you configured in the dashboard. In React, useReferral() wraps generate + share + history.
Step 2: render
Code, share, and history
"use client";
import { useReferral } from "@bricqs/sdk-react";
export function ReferralPanel() {
const { code, shareUrl, defaultMessage, history, share } = useReferral();
return (
<section>
<p>Your code: <code>{code}</code></p>
<button onClick={() => share({ message: defaultMessage })}>
Share via WhatsApp
</button>
<ul>
{history.map((h) => (
<li key={h.id}>
{h.invitedDisplayName ?? "Pending"} ·{" "}
{h.status === "converted" ? `Earned ${h.rewardLabel}` : h.status}
</li>
))}
</ul>
</section>
);
}Step 3: capture
The invitee path
async function handleSignup(email: string, refCode?: string) {
const user = await createUser(email);
// Tell Bricqs about the signup with the referral context.
// The server will record the link; reward issuance fires on the trigger_event.
await emitToBricqs(
user.id,
"user_signup",
{ referral_code: refCode },
`signup:${user.id}`
);
return user;
}
// Later, when the user makes their first purchase:
async function handleFirstPurchase(userId: string, orderId: string) {
await emitToBricqs(
userId,
"first_purchase_completed",
{ order_id: orderId },
`first_purchase:${userId}`
);
// Bricqs auto-issues the inviter and invitee rewards if all checks pass.
}Step 4: attribution
What runs server-side
When the trigger_event fires for a participant who has a referral_code:
1. Resolve referral_code to inviter participant.
2. Run cap checks (inviter quota, invitee quota).
3. Run fraud checks (same device, same payment method, disposable email).
4. If all pass:
- Issue inviter_reward (idempotent on inviter + invitee + program)
- Issue invitee_reward (idempotent on invitee + program)
- Update referral history.
- Fire reward.claimed.v1 webhooks.
5. If any fails: log failure, do not issue, fire fraud webhook for review.
You do not call any endpoint to trigger this. The rules engine handles it.Developer FAQ
Common questions when integrating gamification with Bricqs.
Ready to ship?
Wire it up with the Bricqs SDK or API
Headless SDK for React UIs, REST API for any backend. Same engine behind both.