PopUp Referrals
Check your PopUp referral link, track referral earnings, and see the status of vendors you've referred. This skill is read-only — it retrieves referral data from the PopUp API. It does not send messages, contact vendors, or share links on your behalf.
What This Skill Does
- Retrieves your unique referral code and share URL
- Shows earnings stats (signups, credits, cash earned, account balance)
- Lists referred vendors and their current status
What This Skill Does NOT Do
- It will not proactively suggest sharing referral links
- It will not contact vendors or send DMs on your behalf
- It will not post on social media or comment on posts
- It only responds when you explicitly ask about your referrals
Reward Structure
- $100 cash when a referred vendor subscribes to an annual plan (paid 31 days after subscription start) or stays on monthly billing for 6+ consecutive months
- No cap on total referral earnings
- Referred vendors receive $100 off their first annual subscription ($399 instead of $499)
The $5 account credit for profile publication is only available to vendor-type accounts. Organizer accounts earn the $100 cash reward only.
Authentication
All requests require a Bearer token:
Authorization: Bearer pk_live_...
The token is the POPUP_API_KEY environment variable.
Base URL: https://usepopup.com/api/v1/organizer
Rate limit: 60 requests per minute. HTTP 429 returned with Retry-After: 60 if exceeded.
Endpoints
Get Referral Dashboard
GET /referrals
Returns your referral code, share URL, reward structure, earnings stats, and list of referred users.
Response fields:
| Field | Type | Description |
|---|---|---|
referralCode | string | Your unique referral code |
shareUrl | string | Your referral link |
rewardStructure | object | Current reward tiers |
stats.totalSignups | number | Total vendors who signed up via your link |
stats.totalAnnualSubscriptions | number | Vendors who subscribed annually |
stats.totalCreditsEarned | number | Total credits earned (cents) |
stats.totalCashEarned | number | Total cash earned (cents) |
accountBalance | number | Current account balance (cents) |
referrals | array | List of referred users with name, signup date, and reward status |
Example output:
PopUp Referral Dashboard
────────────────────────────────
Referral Code: ABC123
Share URL: https://usepopup.com/r/ABC123
Total Signups: 12
Credits Earned: $25.00
Cash Earned: $300.00
Account Balance: $125.00
────────────────────────────────
Recent Referrals:
- Jane's Food Truck — signed up Jan 15 — subscribed (annual)
- DJ Mike — signed up Jan 22 — free tier
- Sweet Treats Bakery — signed up Feb 1 — trial active
Response Format
All endpoints return JSON with { "data": ... } wrapper.
Error responses: { "error": "message" } with HTTP status 400, 401, 404, 429, or 500.