Fetch campaign stats with GET /api/oauth2/v2/campaigns/{id}?include=tiers,goals&fields[campaign]=patron_count,paid_member_count,pledge_sum and paginate all members via GET /api/oauth2/v2/campaigns/{id}/members. The most common gotcha: without explicit fields[] and include= parameters, Patreon API v2 returns only {id, type} — no data. Always include a User-Agent header or you get a cryptic 403. Requires campaigns.members OAuth2 scope.
| Fact | Value |
|---|---|
| Platform | Patreon |
| Rate limits | Undisclosed per-second limits; 4xx circuit breaker: 2,000 bad requests in 10… |
| Difficulty | Intermediate |
| Time required | 60 minutes |
| Last updated | May 2026 |
API Quick Reference
Undisclosed per-second limits; 4xx circuit breaker: 2,000 bad requests in 10 min = 30-min IP block
REST only
Patreon API v2 Analytics Overview
Patreon exposes campaign and member data through a JSON:API-compliant REST API. The v2 API is the only supported version — v1 is deprecated and will be removed. All requests must use OAuth2 Bearer tokens, include a User-Agent header, and explicitly specify which fields to return via the JSON:API sparse fieldsets pattern. Without field specifications, responses contain only resource IDs.
https://www.patreon.com/api/oauth2/v2Setting Up Patreon OAuth2 Creator's Access Token
- 1Go to patreon.com/portal/registration/register-clients
- 2Click 'Create Client' and select API v2
- 3Fill in your app name, redirect URI, and description
- 4After creating, copy the Creator's Access Token from the client settings
- 5Request the campaigns.members scope when creating the client
- 6For email access, also request campaigns.members[email] scope
- 7Include a User-Agent header on every request or receive a 403 with no explanation
Key endpoints
/api/oauth2/v2/campaigns/{campaign_id}Fetch campaign statistics. Without explicit fields parameters, returns only {id, type}.
/api/oauth2/v2/campaigns/{campaign_id}/membersList all campaign members. Requires campaigns.members scope. Paginate via links.next cursor.
Step-by-step automation
Configure Auth Headers with User-Agent
Why: Missing the User-Agent header returns a 403 that looks identical to an auth error. This is the most common setup mistake and wastes debugging time. Patreon explicitly documents this requirement.
Set up your authentication headers including the mandatory User-Agent header. Then retrieve your campaign ID — you'll need it for all subsequent requests.
1export PATREON_TOKEN="your_creator_access_token"23# Get your campaign ID (required for member and stats endpoints)4curl -s \5 -H "Authorization: Bearer $PATREON_TOKEN" \6 -H "User-Agent: MyApp - Analytics (admin@myapp.com)" \7 "https://www.patreon.com/api/oauth2/v2/campaigns?fields[campaign]=patron_count,paid_member_count,pledge_sum" \8 | python3 -m json.toolFetch Campaign Stats and Tier Data
Why: The campaign endpoint provides overall stats (total patrons, MRR, paid count) plus tier configuration. Without include=tiers, you can't map member amounts to tier names.
Fetch detailed campaign statistics with tier and goal data. Always specify fields[] for both the campaign and included resources — otherwise you get empty attribute objects.
1curl -s \2 -H "Authorization: Bearer $PATREON_TOKEN" \3 -H "User-Agent: MyApp (admin@myapp.com)" \4 "https://www.patreon.com/api/oauth2/v2/campaigns/$CAMPAIGN_ID?include=tiers,goals&fields[campaign]=patron_count,paid_member_count,pledge_sum,creation_count&fields[tier]=title,amount_cents,patron_count&fields[goal]=amount_cents,completion_percentage,description" \5 | python3 -m json.toolPaginate All Members with Tier Data
Why: A 5,000-patron campaign requires 5 paginated requests at 1,000 per page. The pagination cursor comes from the links.next URL in each response — not a page number.
Fetch all members with currently_entitled_tiers included for tier distribution analysis. Iterate via the links.next cursor until no next link exists.
1# Fetch first page of members2curl -s \3 -H "Authorization: Bearer $PATREON_TOKEN" \4 -H "User-Agent: MyApp (admin@myapp.com)" \5 "https://www.patreon.com/api/oauth2/v2/campaigns/$CAMPAIGN_ID/members?include=currently_entitled_tiers&fields[member]=full_name,patron_status,currently_entitled_amount_cents,last_charge_status,last_charge_date,lifetime_support_cents&fields[tier]=title,amount_cents&page[count]=1000" \6 | python3 -m json.tool | grep -E '"next"|"patron_status"|"full_name"' | head -20Calculate Analytics Metrics
Why: The raw API data gives you patron counts and amounts — you need to aggregate these into business metrics like MRR, churn rate, and tier distribution for the report.
Process the fetched member data to calculate MRR (monthly recurring revenue), active vs declined vs churned counts, tier distribution, and average pledge amount.
1# Not applicable — analytics calculations done programmaticallyComplete working code
Complete Patreon membership analytics automation. Fetches campaign stats, paginates all members, calculates MRR and tier distribution, and outputs a report.
Error handling
Missing User-Agent header. Patreon explicitly requires User-Agent on all API calls — omitting it returns 403 in a way that looks like an auth error.
Add a User-Agent header to every request: 'User-Agent: YourAppName - Description (contact@yourapp.com)'. This is documented in the Patreon API introduction.
Missing fields[] and include= parameters. Patreon API v2 uses JSON:API sparse fieldsets — without explicit field declarations, responses only contain resource type and ID.
Add fields[campaign]=patron_count,paid_member_count,pledge_sum and fields[member]=full_name,patron_status,... to every request. Also add include=tiers for related resources.
Using deprecated Patreon API v1 endpoints. URLs like /pledges, /api/oauth2/api/*, or endpoints without /v2/ are v1 and either 404 or return v1 data.
Use /api/oauth2/v2/ prefix for all endpoints. In v2, use the member resource instead of pledge. Never use /pledges in v2.
Hit Patreon's undisclosed per-second rate limit or made 2,000+ 4xx requests in 10 minutes triggering the circuit breaker.
Honor the retry_after_seconds field in the 429 error response body. For large member lists, add 500ms delays between pagination requests. Fix 4xx errors immediately — repeated 4xx responses trigger a 30-minute block.
Patreon API v2 Rate Limiting
| Scope | Limit | Window |
|---|---|---|
Security checklist
- Store PATREON_TOKEN in environment variables — never hardcode in source files
- Creator's Access Token acts as you — treat it like your Patreon password
- Request only the scopes you need — campaigns.members for analytics, campaigns.members[email] only if you need email
- Implement token refresh logic — access tokens expire approximately monthly
- Log all API calls with timestamps for debugging rate limit issues
- Never log the Authorization header or token value in production logs
Automation use cases
Weekly MRR Dashboard Update
Run weekly to push MRR, patron count, and tier distribution to a Google Sheet or Notion database. Track trends over time to identify growth and churn patterns.
Monthly Churn Report
Compare current active patron count to previous period. Calculate net new patrons and churn rate. Identify the tier with the highest churn for targeted retention campaigns.
Tier Performance Analysis
Calculate revenue per tier, patron count per tier, and percentage of total MRR from each tier. Use this to optimize tier pricing and benefits.
Best practices
- Always specify fields[] parameters — empty attributes objects are the #1 source of confusion with Patreon's JSON:API format
- Always include User-Agent header — missing it returns a 403 that looks like an auth error and wastes debugging time
- Use the Creator's Access Token for your own campaign analytics — it carries all required scopes automatically without OAuth flow complexity
- Never use patreon-js SDK — it's officially deprecated by Patreon and targets the dead v1 API
- Handle all three patron_status values: active_patron, declined_patron, and former_patron — declined patrons still count as members and can recover
- Add 500ms delays between pagination requests for large campaigns to avoid undisclosed rate limits
- Implement token refresh logic from day one — production automations will outlast the ~1-month access token lifetime
Ask AI to help
Copy one of these prompts to get a personalized, working implementation.
I'm building a Patreon membership analytics automation using API v2. I need to fetch all members with pagination (links.next cursor), handle the JSON:API format (must use fields[member]=... or get only {id,type}), and calculate MRR, churn rate, and tier distribution. User-Agent header is mandatory. Can you help me add a week-over-week change calculation that compares current stats to data stored from last week's run in a local JSON file?
Frequently asked questions
Why does the API return only {id, type} with no data?
This is Patreon's JSON:API sparse fieldsets feature. Without explicit fields[] parameters, every resource returns only its ID and type. You must add fields[campaign]=patron_count,paid_member_count,pledge_sum to the campaign endpoint and fields[member]=full_name,patron_status,... to the members endpoint. This is the #1 gotcha for new Patreon API developers.
What's the difference between patron_count and paid_member_count?
patron_count includes all patrons following your campaign, including free-tier followers. paid_member_count only counts patrons with an active paid pledge. pledge_sum is the total of all currently entitled pledge amounts in cents — use this divided by 100 for your MRR figure.
How do I find my campaign ID?
Call GET /api/oauth2/v2/campaigns with your Creator's Access Token. The response includes your campaign's ID, which you'll use for all subsequent endpoints. With a Creator token, you typically have exactly one campaign. Store the campaign ID as a constant once retrieved.
Why am I getting 403 even though my token is correct?
Missing User-Agent header. Patreon explicitly warns: 'Make sure to include a User-Agent header in your code that calls the API, otherwise your calls may be dropped with a 403 response.' Add 'User-Agent: YourAppName (contact@yourapp.com)' to every request header.
How many members can I fetch per page?
The default is 1,000 members per page. If you include pledge_history in the includes parameter, the limit drops to 500 per page. Iterate using the links.next cursor URL returned in the response — not a page number. When there's no next link, you've fetched all members.
Can I use the official Patreon Node.js SDK?
No — the official patreon-js package is deprecated by Patreon itself. Their docs state it 'uses Patreon API v1, which is deprecated and no longer maintained.' Use direct fetch/axios calls or the community patreon-api.ts library for TypeScript projects.
What does declined_patron status mean for revenue calculations?
A declined_patron is someone whose payment failed (card declined, expired, etc.) but who hasn't explicitly cancelled. Their last_charge_status will be 'Declined'. These patrons are not included in MRR calculations since no payment succeeded. They may recover — don't remove them from your member list immediately.
Need this automated?
Our team has built 600+ apps with API automations. We can build this for you.
Book a free consultation