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.