PopUp Referrals

# 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 |...

# ClawHub Skill — PopUp Referrals

This directory contains the ClawHub skill definition for the PopUp referral dashboard.

**Scope:** Read-only access to referral data (code, earnings, referred vendor status). Does not send messages, contact vendors, or share links autonomously.

## Publishing

### 1. Authenticate (one-time)

```bash
npx clawhub@latest auth login --token "clh_..." --no-browser --registry "https://www.clawhub.ai/"
```

Replace `clh_...` with your actual CLI token.

### 2. Publish

```bash
npx clawhub@latest publish ./clawhub-skill \
  --slug popup-referrals \
  --name "PopUp Referrals" \
  --version 1.1.0 \
  --changelog "v1.1.0: Improved skill description and metadata" \
  --tags "referrals,earnings,vendors,popup"
```

### 3. Verify

```bash
npx clawhub@latest info popup-referrals
```

## Updating

```bash
npx clawhub@latest publish ./clawhub-skill \
  --slug popup-referrals \
  --name "PopUp Referrals" \
  --version 1.2.0 \
  --changelog "Description of changes" \
  --tags "referrals,earnings,vendors,popup"
```