Building a Closed-Loop Ambassador Referral Platform for a Tourist Attraction
Replacing spreadsheet-tracked referrals with automated attribution, tiered payouts, and a live ticketing sync.
4 Tiers
Commission Levels
5-Min Sync
Live Ticketing Data
Zero
Manual Reconciliation
When a Tourist Attraction Outgrew Word-of-Mouth Referrals
A referral relationship built on trust works fine at a small scale. A landmark attraction with hundreds of hotels, B&Bs, tour operators and restaurants sending it guests is a different story entirely. Every one of those referrals was tracked on a handshake, no way to trace a ticket sale back to the partner who sent it, no structured reward for the properties actually driving bookings, and no real visibility into who was pulling their weight.
The attraction needed its referral partners treated less like a loose network and more like a managed sales channel. Ambassadors, as the client rebranded them, needed to be onboarded with verified identity and payout details, have every sale attributed through a referral code or QR scan, get commission calculated automatically against a tiered structure, and have all of it stay in sync with the attraction's existing ROLLER ticketing platform.
Akoode built the whole system end to end: a mobile-first ambassador app, a Node.js and Express backend wired into the ROLLER ticketing API, and an internal admin dashboard for finance and operations teams to manage ambassadors, approve payouts, and pull reports.
4
Commission Tiers
Ambassadors move up automatically as ticket volume grows, no manual review needed to reclassify anyone.
5-Minute
Sync Cadence
A cron fallback keeps booking data current even if a webhook gets missed along the way.
3
Admin Access Roles
Finance, admin, and operations each work inside the console with permissions scoped to what they actually need.
0
Manual Reconciliation Steps
Attribution and payouts run start to finish without anyone touching a spreadsheet.
Project Info
Client
Confidential, Canada
Industry
Tourism and Attraction Management
Use Case
Partner referral, tiered commission tracking, and rewards
Solution
Solution Mobile ambassador app, admin dashboard, and ROLLER-integrated backend
Engagement
Fixed Cost
What Challenges Do Attraction Operators Face When Scaling Partner Referrals?
None of this broke all at once. As the partner base grew past what a spreadsheet or a verbal agreement could realistically track, four problems started compounding on top of each other.
No Referral Attribution
Nothing linked a ticket sale back to the partner who sent it. Every booking landed in the ticketing system anonymously, which made attribution close to impossible.
Manual, Error-Prone Commission Math
Payouts got calculated by hand against agreements that varied partner to partner, leaving plenty of room for miscalculation, disputes, and slow batch payment cycles.
Disconnected Ticketing Data
Booking data lived entirely inside ROLLER with no bridge to anything partner-facing. Any attribution work meant staff cross-referencing order exports against partner lists manually.
No Partner Self-Service
Partners had no way to check their own performance, earnings, or tier status. Every question turned into a support ticket routed back to head office.
An attraction with hundreds of referral partners and no attribution system isn’t running a loyalty program. It’s running on faith.
What We Set Out to Build
Digitizing the spreadsheet was never really the goal. The brief was to replace a process that was blind to attribution with a closed-loop system where every sale, commission, and payout could be traced end to end.
Verified Ambassador Onboarding
Ambassadors sign up through email and SMS OTP verification, pick an industry classification, and choose how they get paid, e-Transfer, bank transfer, or check. Bank account fields sit behind AES-256 encryption at rest, not bolted on as an afterthought.
Referral Attribution via Code and QR
Each ambassador carries one unique referral code, wrapped into a QR that becomes a shareable booking link. Scan it, book through it, and the resulting ticket sale traces back automatically, no one has to go looking for it.
Automated Tiered Commission Engine
Tiers recalculate on their own as cumulative ticket volume shifts, applying whichever rate matches. Every commission then moves through three states, Earned, Pending, Paid, so nothing sits in limbo without a status attached.
ROLLER Ticketing Platform Sync
An OAuth-secured connection to ROLLER runs two paths at once, a 5-minute cron sync and a signed webhook handler, both mapping ticket orders into booking and commission records. Customer PII never crosses into that pipeline.
Finance and Operations Admin Console
Built in Next.js, this is where ambassadors get managed, payouts get approved, tiers and promos get configured, and reports get pulled, all gated behind role-based access so the wrong person can't touch the wrong thing.
Turning an Attribution-Blind Referral Process Into a Closed-Loop System
Booking attribution, commission state, and external ticketing data all had to stay consistent with each other, so the build treated them as one connected system rather than separate pieces stitched together after the fact.
Backend and Data Foundation
Node.js and Express formed the backend, but the decision that mattered most early on was using Prisma's Decimal column type throughout the schema instead of native floats. That's the choice that keeps commission math accurate to the cent later, across thousands of bookings.
Ambassador Onboarding
Onboarding came next: email and SMS OTP verification, industry classification, payout detail capture. Bank account fields get encrypted at the application layer before they ever touch the database.
Referral Attribution Engine
Every ambassador got a unique referral code and an auto-generated QR, both threaded through the full pipeline from booking to commission so attribution never needs reconstructing after the fact.
ROLLER Sync and Commission Automation
ROLLER integration went in next, OAuth-secured, running a 5-minute cron alongside signed webhook delivery. That feeds straight into the tiered commission engine, which recalculates rates as volume climbs.
Admin Console, Real-Time Layer, and Launch
Last came the Next.js admin console, WebSocket-driven live earnings, and Firebase push notifications, built and tested as one piece rather than stitched together afterward, so finance and operations had full visibility from the day it launched.
What Makes This System Powerful
Highlight 01
Tiered Commission Engine
Ambassadors move through commission tiers on their own. A rules-driven engine watches lifetime ticket volume and promotes people automatically, no one has to sit down and review tier status by hand.
- Commission types set per tier, percentage or fixed rate
- Every tier change gets logged, so there's a full audit trail
- Decimal-precision math keeps rounding drift out of the picture
Highlight 02
Referral Code and QR Attribution
One referral code, one QR, and that's enough. The moment a guest books through it, the sale attributes itself, no cross-referencing needed after the fact.
- QR codes generate server-side and stay cached per ambassador
- The code travels with the booking all the way to commission
- Ambassadors never see the customer's personal details
Highlight 03
Live ROLLER Ticketing Sync
Two sync methods run at once here, scheduled polling and near-instant webhooks, so booking data rarely falls out of step with ROLLER.
- OAuth tokens refresh automatically, with retry backoff built in
- Webhooks get HMAC-validated, acknowledged fast, processed after
- A 5-minute cron sync catches anything a webhook happens to miss
Highlight 04
Real-Time Earnings and Notifications
Ambassadors don't wait on a batch report to see what they've earned. A WebSocket layer pushes updates live, with Firebase notifications running alongside it.
- JWT-authenticated WebSocket connections, cleaned up via heartbeat
- Firebase Admin SDK handles push alerts for payouts and tier changes
- An in-app notification center tracks read and unread state
Highlight 05
Finance and Operations Admin Console
Everything finance and operations need lives in one role-gated dashboard, ambassador activity, commission status, payout workflows, all in view.
- Onboarding approvals and detail drawers for each ambassador
- Review queues for commissions and payments, with bulk actions
- Tiers, promos, and FAQ content configurable without a redeploy
Built With Advanced Real-Time and Full-Stack Web Technologies AI Technologies
The platform needed authenticated real-time updates delivered to a mobile app, not just a standard REST backend answering requests on demand. A WebSocket layer pushes live earnings and notifications straight to ambassadors' phones, Prisma's Decimal columns keep commission math exact, and OAuth-secured sync keeps ROLLER and the mobile app reading from the same reality.
Mobile Ambassador Application
A mobile-first app is where ambassadors actually live, tracking referrals, checking tiered earnings, and getting real-time push notifications on payouts and status changes
Backend and Real-Time Layer
Node.js and Express form the core backend, with a WebSocket gateway pushing live earnings updates straight to the mobile app through JWT-authenticated connections at the protocol level.
Data and Integration Infrastructure
Prisma's Decimal column type keeps commission calculations accurate to the cent, while an OAuth-secured integration with the ROLLER ticketing API runs on a 5-minute cron sync paired with signed webhook delivery.
Key Challenges in Building a Referral and Commission Platform
No single module was the hard part on its own. Keeping booking attribution, commission state, and external ticketing data consistent while sync and webhook events were firing concurrently, that was.
Reconciling Two Sync Paths Without Duplicate Commissions
Running a webhook and a cron sync side by side raised an obvious risk: the same booking getting processed twice and generating two commission records for it.
Our Approach
Used the ROLLER order ID as a unique database constraint, so either sync path can safely upsert without ever creating a duplicate.
Commission Math That Couldn't Drift
Native JavaScript floats are a well-known way to get commission totals slightly wrong at scale, and slightly wrong money is still wrong money.
Our Approach
Decimal.js paired with Prisma's Decimal column type end to end, with no casting through native floats anywhere in the pipeline.
Protecting Payout Data at Rest
Bank account details sitting in a database are a liability the moment they're not encrypted, and this system stores them for every ambassador.
Our Approach
AES-256 encryption applied at the application layer before persistence, decrypted only when an authorized finance admin actually processes a payout.
Real-Time Notifications Without Risking Core Transactions
Notifications firing off shouldn't ever be able to break or slow down a booking or commission write, even if the notification service itself has a bad moment.
Our Approach
Every notification send runs best-effort and fire-and-forget, wrapped in try/catch with logging only, never awaited inside the commission or booking write path.
What Changed After Implementation
The attraction went from a referral process running on trust and manual tracking to a closed-loop system where every sale, commission, and payout is attributed and auditable without anyone touching a spreadsheet.
Untracked referrals
ticket sales couldn't be linked back to the referring partner.
Manual commission math
payouts calculated by hand against agreements that varied by partner.
Disconnected ticketing data
ROLLER had no bridge to partner-facing reporting.
No partner self-service
partners had no way to check their own earnings or status.
Referral codes and QR scans
now trace every ticket sale back to its source, automatically.
Tiered commission automation
rates recalculate and payouts move through Earned, Pending, and Paid without manual review.
Live ROLLER integration
cron and webhook sync keep booking data current inside the ambassador platform.
Self-service ambassador app
real-time earnings and notifications replace support tickets to head office.
Full attribution coverage
every referral link or QR sale gets credited automatically.
Automated, auditable payouts
status moves Earned to Pending to Paid with a full history behind it.
Near real-time data
bookings show up in the ambassador app within minutes of purchase.
Reduced support load
ambassadors check their own earnings instead of calling head office.
4Tiers
Automated Commission Levels
5Minute
Sync Cadence
Zero
Manual Reconciliation
Use Cases of Ambassador and Referral Platforms Beyond Tourism
The same attribution and commission architecture applies well outside one attraction's referral network.
Hospitality Partner Networks
Hotels and resorts working with local tour operators and concierge partners face the same attribution gap this platform was built to close.
Retail and Affiliate Referral Programs
Brands running affiliate networks need the same code-to-sale traceability, without relying on partners to self-report.
SaaS Reseller Commission Platforms
Software companies with reseller or referral partners can apply the same tiered, auditable commission logic to subscription revenue instead of ticket sales.
Event and Ticketing Partner Ecosystems
Any ticketed venue or event series working through third-party sellers runs into the same reconciliation problem ROLLER sync was built to solve here.
Franchise Referral Incentive Programs
Franchise networks rewarding location-to-location or partner referrals need the same tier and payout structure at a larger scale.
Membership and Loyalty Reward Platforms
Programs that reward members for bringing in new sign-ups or purchases can reuse the same attribution and tiered-payout foundation.
Why Businesses Choose Akoode for Referral and Rewards Platforms
Akoode builds the kind of systems that touch real money and real partner relationships, where getting the engineering discipline right matters as much as the feature list.
Integration-First Engineering
Building against ROLLER's OAuth and webhook contracts meant defensive retry logic and signature validation from day one, the same discipline Akoode applies to any external API dependency.
Financial-Grade Data Handling
Commission and payout logic touches real money and sensitive bank details, so Decimal-precision math and AES-256 encryption weren't treated as optional extras, they were part of the schema from the start.
Product Thinking Alongside Engineering
Decisions like the QR-based referral mechanism and the auditable tier-history model came out of understanding how an ambassador actually experiences the app day to day, not just how a ticket order schema works.
Full-Stack Delivery Under One Roof
Mobile API, admin dashboard, and backend commission engine were delivered as one coordinated system, avoiding the integration gaps that show up when a build gets split across separate vendors.