Affiliate and referral system on Vareons for online stores in Egypt: links, codes, tracking, and order attribution
The referral system on Vareons lets a merchant create referral links with custom codes, track clicks and signups from the ?ref= parameter, and attribute orders and revenue per code from the same /dashboard/affiliate board.
Last verified: 2026-09-19
The referral system is managed from /dashboard/affiliate, which renders the AffiliatePage component with tabs — overview, analytics, management, security, tools, and resources — plus "simple" and "advanced" modes inside the page. The simple mode is the real database-backed part, while the advanced panels (analytics, campaigns, commissions, payouts, leaderboard, fraud detection, geo and device, multi-level, notifications, custom pages, benchmarks, training) currently read mock data from dataStructure/affiliate/mockData and do not persist to the database.
The simple mode has three pieces: SimpleReferralSteps for creating a link, SimpleStats for totals, and SimpleLinksList for the latest 10 links with per-code orders and revenue. Each link is stored in the SimpleReferralLink collection with the merchant userId, an uppercase unique code, an optional name, a required url, and clicks/signups/conversions counters starting at zero, with a compound index on userId and creation date for fast queries.
Link creation goes through POST /api/affiliate/simple/create-link at 20 requests per minute: the code is required, at most 20 characters, uppercased; the url is required; the name is optional. Codes are globally unique, so a duplicate returns 409 CODE_ALREADY_EXISTS. On success the API returns 201 with the id, code, and counters. The list endpoint GET /api/affiliate/simple/links builds the storefront URL dynamically as {subdomain}.{baseDomain}/?ref={CODE} from the merchant domain stored on User.domain plus request host headers, and attaches per-link order counts and total revenue via an orders aggregation. The stats endpoint GET /api/affiliate/simple/stats sums clicks/signups/conversions, then computes totalOrders and ordersPerRef from the data.affiliateCode field on orders. Updates go through PUT /api/affiliate/simple/update-link, deletion through DELETE /api/affiliate/simple/delete-link, code checks through verify-code, simple click tracking through track-click, and link copying through copy-link.
Visitor tracking starts in the ReferralTracker component, which reads ?ref= from the URL and posts to /api/referral/track with UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content) into the Partnership system, creating a ReferralClick document with partnershipId, referralCode, IP address, user agent, referrer, country, city, UTM fields, the converted flag with convertedUserId, and subscription data (plan from free to enterprise, amount, EGP currency, month count, renewal flag). To avoid double counting it uses sessionStorage per session, persists the code in localStorage under oro_referralCode for 30 days with a partner_ref cookie for one year, while the legacy system keeps referralCode for 24 hours only. At signup, pages/api/users/register.js reads the stored code and forwards it to track-signup without blocking registration on failure, incrementing signups and linking the new user to the link.
Order attribution relies on the data.affiliateCode field on the order document with data.totals.grandTotal for revenue, aggregated per code separately for each tenant. Any order carrying the code therefore shows up in SimpleStats and in the orders and revenue columns of SimpleLinksList.
Around the system there are supporting services: AI Copilot affiliate tools in features/ai-copilot/tools/affiliate/index.ts read referral dashboards and manage simple links (create/update/delete) under marketing.view for reads and marketing.create/edit/delete for mutations, the affiliate app in the apps marketplace (User.enabledApps) behind a plan gate, the affiliate category in audit logs, affiliate toggles in notification preferences, and the affiliate-code column in the orders table.
The buttons a merchant sees on the page are: generate code, create link, copy link, the "create new link" and "manage links" tabs, link enable/disable, link delete, name edit, the simple/advanced switch, CSV/Excel/PDF export buttons, the interactive commission calculator, campaign creation, the payouts table filters (paid, pending, rejected), notification settings (channels: dashboard, email, push, SMS; frequency: instant, hourly, daily, weekly), landing-page templates, the lifetime-referral toggle, and training resources.
Setup steps in Vareons
Open the affiliate page
From the dashboard open /dashboard/affiliate from the sidebar (TrendingUp icon), and stay in “simple” mode because the advanced panels show mock data.
Create the referral link
In the create-new-link tab enter the campaign name, click generate code or type a code up to 20 characters (uppercased automatically), enter the target page URL, then click create link and wait for the 201 response.
Copy and share the link
Click copy link to get the {subdomain}.{baseDomain}/?ref={CODE} form, share it on social or email, and follow it from the manage-links tab.
Verify tracking and attribution
Open the link yourself and confirm clicks rise in SimpleStats, register a test account to confirm signups rise, then place an order carrying the code and confirm it appears in the orders and revenue columns.
Manage the links
From manage links enable or disable any link, edit its name, delete finished ones, and remember the list shows only the latest 10 links.
Frequently asked questions
Does Vareons support affiliate marketing?
Yes. From /dashboard/affiliate you can create links with custom codes and track clicks, signups, and per-code order and revenue attribution via SimpleReferralLink, ReferralClick, and Partnership.
How do I create a new referral link?
Open /dashboard/affiliate in simple mode, enter the campaign name and target URL, generate a code up to 20 characters, then click create link. Codes are globally unique — a duplicate returns 409 — and the final link is ?ref={CODE} on your store domain.
How does ?ref= tracking work and how long does it last?
The ReferralTracker component sends the code with UTM to /api/referral/track once per session, stores oro_referralCode for 30 days with a one-year partner_ref cookie, while the legacy system keeps referralCode for 24 hours only.
How are orders and revenue attributed to a referral code?
The order carries data.affiliateCode, and the simple/stats and simple/links endpoints aggregate orders and revenue (data.totals.grandTotal) per code within your store, shown in the stats and in the orders and revenue columns.
Are the commission, payout, and fraud panels real?
No. Those advanced panels (commissions, custom rules, payouts, leaderboard, campaigns, fraud detection, geo, multi-level, notifications, landing pages, exports, training) read mock data from mockData and do not persist; the real part is simple links, tracking, and attribution.
Troubleshooting
1) If creation returns 409, the code is taken globally: change it or generate a new one. 2) If it returns 400, check the code (required, up to 20 characters) and the url field (required). 3) If clicks do not rise, open the link in the correct ?ref= form, allow local storage, and use a fresh session (tracking fires once per session). 4) If orders are not attributed, confirm the order carries the correct uppercase data.affiliateCode and the merchant owns the link. 5) If the list looks empty, confirm you are in simple mode, that links exceed 10 (the list shows the latest only), or that the userId format mismatches.
Important limitations
• Codes are globally unique, capped at 20 characters, uppercased, and the links list shows only the latest 10. • The advanced panels (analytics, campaigns, commissions, payouts, leaderboard, fraud detection, geo, multi-level, notifications, pages, exports, training, benchmarks) are non-persisted mock data. • The legacy track and track-signup endpoints mutate in-memory data only; real tracking goes through /api/referral/track with the Partnership and ReferralClick models. • Order attribution depends on data.affiliateCode being written at order creation, so old orders without the code are not retro-attributed.