The Friendbuy referral data model works best when you treat it as a chain: Advocate → Referral → Conversion → Reward. Each object answers a different question. Who shared? Who was invited? Did that person buy or complete the target action? Who gets paid, credited, or thanked?
TLDR: Friendbuy connects referral activity by tying an advocate to a referred customer, tracking whether that customer converts, then issuing a reward based on campaign rules. For example, if 10,000 advocates share links, 18% generate at least one referral, 7% of referred visitors convert, and each reward costs $10, you can forecast both growth and payout liability. The cleanest setup is to pass stable customer IDs, order IDs, and conversion metadata into the API. If those fields are messy, reporting gets annoying fast.
Why the data model matters
Referral programs look simple from the outside. A customer shares a link. A friend buys. Someone gets a coupon. Done.
Under the hood, though, Friendbuy has to track identity, attribution, campaign rules, conversion events, fraud checks, and reward states. That means the API data model needs clear links between multiple records. If those links break, teams end up asking painful questions like:
- Which advocate drove this order?
- Was this conversion already credited?
- Did the referred customer qualify?
- Has the reward been approved, pending, canceled, or fulfilled?
- Why does the dashboard show 43 conversions while the warehouse shows 41?
The catch is that referral data often crosses systems. Your ecommerce platform owns the order. Your CRM owns the customer. Friendbuy owns the referral journey. Your finance team cares about reward cost. The API is the bridge between those pieces.
The Advocate: the person who shares
The Advocate is the existing customer, subscriber, or user who promotes your brand. In Friendbuy, this person is usually tied to a unique identifier from your system. That might be a customer ID, email address, account ID, or another stable value.
A good advocate record should make it easy to answer:
- Who is sharing?
- Which campaign are they part of?
- What referral link or code belongs to them?
- How many referrals and conversions have they generated?
- What rewards have they earned?
Do not rely only on email if your product allows email changes. Use a durable internal ID when possible. Emails are useful for communication, but IDs are better for matching records over time.
Typical advocate data may include:
- Customer ID
- First and last name
- Referral code or referral link
- Campaign ID
- Created timestamp
- Status or eligibility flags
If an advocate is removed, blocked, or becomes ineligible, that status should be reflected before new rewards are approved. Honestly, it feels like a small detail until one customer receives five credits for orders your fraud team already rejected.
The Referral: the invited person or referral action
The Referral represents the connection between an advocate and a referred person. This may begin when someone clicks a referral link, enters a referral code, submits an email, or lands on a campaign page.
Think of the referral as the attribution record. It says, “This potential customer came from this advocate, through this campaign, at this time.”
A referral record may include:
- Referral ID
- Advocate ID
- Referred customer email or ID
- Campaign ID
- Referral code used
- Click or signup timestamp
- Source or channel
- Attribution status
This object is where many reporting problems begin. A referred shopper may click on Monday, buy on Friday, and use a different email at checkout. If your integration does not pass enough identity data back to Friendbuy, the referral may not match the conversion.
One helpful pattern is to store the Friendbuy referral identifier, referral code, or tracking token in your own checkout session. Then send it back with the purchase or conversion event. That extra field can save hours of cleanup later.
The Conversion: the qualified action
The Conversion is the event that proves the referral worked. For ecommerce, that is often a first purchase. For SaaS, it may be a paid subscription, booked demo, activated account, or completed onboarding step.
Friendbuy needs conversion data to determine whether campaign rules were met. A conversion record should be precise. Vague events cause duplicate credit, missed rewards, and reporting gaps.
Useful conversion fields include:
- Order ID or event ID: prevents duplicates.
- Customer ID: identifies the referred customer.
- Advocate or referral ID: ties the event to the original share.
- Revenue amount: supports ROI reporting.
- Currency: prevents payout confusion.
- Timestamp: keeps attribution windows clear.
- Product or plan: helps apply campaign rules.
For example, a campaign might reward advocates only when a referred customer places a first order over $75. If the API sends only “purchase complete” with no order value, Friendbuy cannot apply that rule cleanly. You may end up approving rewards manually, which nobody enjoys.
The Reward: the outcome of a qualified conversion
The Reward is the benefit issued after conversion rules are satisfied. It may go to the advocate, the referred customer, or both. Common rewards include discount codes, store credit, gift cards, loyalty points, cash payouts, or account credits.
Rewards usually have a lifecycle. They are not always issued instantly. Brands may wait for fraud screening, payment capture, refund windows, or subscription activation.
A reward may move through statuses such as:
- Pending: earned but not yet approved.
- Approved: qualified and ready for fulfillment.
- Fulfilled: sent, credited, or applied.
- Canceled: rejected due to refund, fraud, or rule failure.
- Expired: no longer usable after a time limit.
The reward object should connect back to the advocate, referral, conversion, and campaign. That gives marketing, support, and finance a shared trail. When a customer asks, “Where is my reward?”, support should not need to check four tools and guess.
How the four objects connect
The core relationship can be described like this:
- An advocate receives or creates a referral link.
- A potential customer clicks the link or uses the code, creating a referral.
- That referred person completes a required action, creating a conversion.
- Friendbuy applies campaign rules and creates one or more rewards.
In a two-sided campaign, one conversion may create two rewards: one for the advocate and one for the referred customer. In a tiered campaign, the tenth successful referral may create a larger reward than the first nine. This is why clean object relationships matter.
A simple example:
- Customer A is advocate ADV 1001.
- Customer A shares code SARA20.
- Customer B clicks the link and becomes referral REF 8821.
- Customer B places order ORD 5559 for $120.
- Friendbuy records conversion CONV 3302.
- The campaign issues a $20 advocate reward and a 20% friend discount.
That chain gives you attribution, payout history, and campaign performance in one connected model.
Analytics built on the model
Once the data is clean, referral analytics become much more useful. You can measure each step instead of staring at one blended number.
Key metrics include:
- Share rate: percentage of customers who become advocates.
- Referral click rate: clicks per advocate or per share.
- Referral conversion rate: conversions divided by referred visitors.
- Reward approval rate: approved rewards divided by pending rewards.
- Cost per referred customer: total reward cost divided by new customers.
- Referred customer revenue: revenue generated by referral-driven buyers.
Say 50,000 customers see a referral prompt. If 12% share, that creates 6,000 advocates. If each advocate drives 1.4 referred visits on average, that creates 8,400 visits. At a 6% conversion rate, you get 504 new customers. If rewards cost $15 each, your direct reward cost is $7,560 before platform and operational costs.
Best practices for API implementation
Use stable IDs everywhere. Pass your internal customer ID, order ID, and campaign ID whenever possible. Friendbuy can only connect what you send.
Make conversion events idempotent. If the same order is sent twice, the API should not create two conversions or two rewards. Use a unique order or event ID every time.
Send enough metadata. Revenue, currency, product type, coupon used, and customer status can all affect eligibility. Missing fields may force manual review.
Track reward states in your own systems if customer support needs them. A support agent should be able to see whether a reward is pending, approved, fulfilled, or canceled without asking engineering.
Use webhooks or scheduled syncs for status changes. Rewards and conversions do not always stay fixed. Refunds, cancellations, and fraud reviews can change the final outcome.
Common mistakes to avoid
- Using email as the only identifier.
- Sending purchase events without order IDs.
- Failing to pass referral codes into checkout.
- Approving rewards before refund windows close.
- Mixing test campaign data with production reporting.
- Ignoring canceled or rejected reward states in analytics.
The Friendbuy referral API data model is not just a technical detail. It is the structure behind growth reporting, reward accuracy, customer trust, and campaign ROI. Get the advocate, referral, conversion, and reward relationships right, and your referral program becomes far easier to measure, support, and scale.
