tier-management
Evaluate and update Pollinations user tiers. Check balances, upgrade devs, batch process users. For finding users with errors, see model-debugging skill first.
When & Why to Use This Skill
The Tier Management skill is a specialized operational tool for the Pollinations ecosystem, designed to streamline user account administration and subscription scaling. By integrating GitHub contribution data with Cloudflare D1 database management and Polar billing synchronization, it provides a robust framework for managing user access levels, rewarding community engagement, and resolving quota-related bottlenecks through automated batch processing.
Use Cases
- Contribution-Based Promotion: Automatically verify GitHub stars, issues, or code contributions to upgrade users from 'Spore' to 'Seed' or 'Flower' tiers.
- Cross-Platform Synchronization: Ensure that updates to a user's tier in the internal database are instantly reflected in their Polar subscription status.
- Error-Driven User Support: Identify users encountering 402 billing errors and proactively evaluate them for developer-tier upgrades to reduce friction.
- Automated Community Engagement: Generate and post standardized GitHub notifications to inform users of their new tier benefits and priority queue access.
| name | tier-management |
|---|---|
| description | Evaluate and update Pollinations user tiers. Check balances, upgrade devs, batch process users. For finding users with errors, see model-debugging skill first. |
Requirements
Before using this skill, ensure you have:
- GitHub CLI:
brew install gh && gh auth login - Node.js/npx:
brew install node - Wrangler:
npm install -g wrangler - jq:
brew install jq(for parsing JSON) - sops:
brew install sops(for decrypting secrets)
Must run from the pollinations repo root with access to enter.pollinations.ai/.
Tier Levels
| Tier | Emoji | Pollen/Day | Criteria |
|---|---|---|---|
| spore | 🍄 | 1 | Default (new signups) |
| seed | 🌱 | 3 | GitHub engagement |
| flower | 🌸 | 10 | Contributed code/project |
| nectar | 🍯 | 20 | Strategic partners |
| router | 🔌 | 100 | Infrastructure partners |
Upgrade Paths
🍄 Spore → 🌱 Seed
- ⭐ Starred the pollinations repo
- 💬 Opened an issue or PR
- 💳 Made a purchase
🌱 Seed → 🌸 Flower
- 🛠️ Pushed code to pollinations/pollinations
- 📦 Has a project in our showcase
- 🌐 Built something open-source using our API
Evaluate User Tier
Check for Flower (any ONE qualifies)
Has commits to pollinations?
gh api 'search/commits?q=repo:pollinations/pollinations+author:USERNAME' --jq '.total_count'
Has a project in our lists?
grep -ri "author.*USERNAME" pollinations.ai/src/config/projects/
Check for Seed (any ONE qualifies)
Involved in issues/PRs?
gh api 'search/issues?q=repo:pollinations/pollinations+involves:USERNAME' --jq '.total_count'
Starred repo?
.claude/skills/tier-management/scripts/fetch-stargazers.sh USERNAME
Update User Tier
⚠️ IMPORTANT: You MUST update BOTH the database AND Polar subscription. The DB tier controls what tier the user CAN activate. The Polar subscription is what they HAVE activated.
Recommended: Use the Script
.claude/skills/tier-management/scripts/update-tier.sh USERNAME TIER
Example:
.claude/skills/tier-management/scripts/update-tier.sh s0974092 flower
This script automatically:
- Finds the user by username or email
- Updates the database tier
- Updates the Polar subscription (via sops for auth)
- Verifies the change
Manual Method
Step 1: Find user
cd enter.pollinations.ai
npx wrangler d1 execute DB --remote --env production \
--command "SELECT id, github_username, email, tier FROM user WHERE LOWER(github_username) LIKE '%USERNAME%';"
Step 2: Update database
npx wrangler d1 execute DB --remote --env production \
--command "UPDATE user SET tier='TIER' WHERE github_username='USERNAME';"
Step 3: Update Polar subscription
export POLAR_ACCESS_TOKEN=$(sops -d secrets/prod.vars.json | grep POLAR_ACCESS_TOKEN | cut -d'"' -f4)
npx tsx scripts/manage-polar.ts user update-tier --email USER_EMAIL --tier TIER
Add --dryRun to preview changes without applying.
Step 4: Notify user on GitHub
🎉 **Tier Upgrade Complete!**
Hey @USERNAME! You've been upgraded to **[EMOJI] [TIER] tier**! ✨
Your benefits:
- [POLLEN] pollen/day
- ⚡ Priority queue
- 🎨 All standard models
Thanks for being part of Pollinations! 🚀
Batch Processing
Find Users with Billing Issues
Use the model-debugging skill to find users hitting 402 errors (billing/quota):
# Find spore-tier users with >10 402 errors in last 24 hours
.claude/skills/model-debugging/scripts/find-402-users.sh 24 10 spore
# Save to file for batch processing
.claude/skills/model-debugging/scripts/find-402-users.sh 24 10 spore | cut -f1 > /tmp/users.txt
Note: 402 = billing issues (pollen balance, key budget). 403 = permission issues (model access denied).
Check if User is a Developer
# Check single user
.claude/skills/tier-management/scripts/check-github-dev.sh OliverCWY
# Output: dev: repos=12 followers=13 account_year=2017
Batch Upgrade Devs to Seed
# Dry run first (no changes)
.claude/skills/tier-management/scripts/upgrade-devs.sh /tmp/users.txt --dry-run
# Apply upgrades
.claude/skills/tier-management/scripts/upgrade-devs.sh /tmp/users.txt
The script:
- Checks GitHub profile for dev activity (repos, followers, account age)
- Only upgrades users currently on spore tier (won't downgrade)
- Has 2s delay between GitHub API calls to avoid rate limiting
- Shows summary of upgraded/skipped users
Check User Balance
.claude/skills/tier-management/scripts/check-user-balance.sh username_or_email
Legacy Batch Evaluate
export ENTER_ADMIN_TOKEN=your_token
export TIER_EVAL_GIST_ID=your_gist_id # optional
.claude/skills/tier-management/scripts/batch-evaluate.sh
Polar Product IDs (Production)
| Tier | Product ID |
|---|---|
| Spore | 01a31c1a-7af7-4958-9b73-c10e2fac5f70 |
| Seed | fe32ee28-c7c4-4e7a-87fa-6ffc062e3658 |
| Flower | dfb4c4f6-2004-4205-a358-b1f7bb3b310e |
| Nectar | 066f91a4-8ed1-4329-b5f7-3f71e992ed28 |
| Router | 0286ea62-540f-4b19-954f-b8edb9095c43 |
Notes
- DB tier = what user CAN activate
- Polar subscription = what user HAS activated
- If no Polar subscription, user must click "Activate" at enter.pollinations.ai