Documentation › User Guides › Device Owners › Stage 3 › Referrals

Earn from referrals

Refer another device owner, earn a percentage of their earnings for a fixed window. The program is implemented in backend/app/services/referral/ and backend/app/services/referral_service.py — verified to exist and operational. Numbers below come from backend/app/models/referral.py.

How it works

1. Find your referral code on the dashboard at Settings → Referrals, or generate share links to Twitter / LinkedIn / WhatsApp [VERIFY: share UI surface in web/src/pages/devices/ — referral_v2.py confirms backend support].
2. A new user signs up via your link. Their account stores your code in referral_code_used.
3. They activate by becoming an earning device owner. Status moves from pending → active. [VERIFY: exact activation trigger — likely first approved earning, confirm against referral_service.py at GA].
4. You earn a bonus on every earning they generate, for the bonus duration.
5. The referral expires automatically when the duration elapses. Status moves to expired. Future earnings of theirs no longer pay you.

The numbers (default tier)

From backend/app/models/referral.py:

Field	Default
bonus_rate	5% of referee earnings
bonus_duration_days	180 (6 months)

So if you refer someone who earns $100 over 6 months, you receive $5 in referral bonuses on top of your own earnings.

Tiers — earn more per referral as you refer more

The platform tracks a ReferralTier (verified in backend/app/services/referral/referral_v2.py::get_user_tier). The more active referrals you have, the higher tier you sit at, and the higher your reward_percentage on future referrals. Tier configuration lives in the referral_tiers table — exact tier names and thresholds [VERIFY: tier ladder at GA — configurable in database, not hard-coded].

The dashboard shows your current tier and the count of referrals needed to reach the next.

Stacking with your own earnings

Referral bonuses are a separate revenue line. They:

• Hit your balance as their own earning records (earning_source: marketplace or similar)
• Flow through the same pending → approved → paid lifecycle
• Roll up into the same Stripe Connect payout
• Count toward the same tax forms (1099-K / DAC7)

They do not reduce the referee's earnings. The bonus comes from the platform's share, not theirs.

B2B referrals (different program)

If you refer an organization (not a device owner), a separate program applies — verified in backend/app/services/referral/referral_v2.py::create_b2b_referral. Default commission is 5% of the referred organization's spend. Reach out via hello@getzyra.io if you're connected to a buyer-side prospect.

What doesn't work

• Self-referrals. Same account, same hardware, different sign-up email — the system detects duplicates.
• Inactive referees. A referee who signs up but never earns generates no bonus.
• Off-platform incentives. Don't offer kickbacks to people to use your code; it violates terms.

See your referral dashboard

Settings → Referrals shows:

• Your current code and share links
• Active / pending / expired referrals
• Total bonus earned to date (total_bonus_earned column)
• Your current tier and next-tier progress

Troubleshooting

• Referee signed up but doesn't show. Confirm they entered your code at signup, not after. The referred_user_id is set once and only once.
• Referee is earning but I'm not. Check the referral's activated_at and status. If still pending, their first earning hasn't approved yet.
• My bonus expired. That's by design — 180 days from activation. Referees are locked to the original referrer for life and cannot sign up again under a different code.

What's next

That closes Stage 3. Stage 4 covers power-user topics: API access, automation, advanced fleet management. Back to Device Owner index →

Last reviewed: 2026-05-21