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.