API Reference
The REST API v1 lets you manage packages, customers, subscriptions, and analytics programmatically.
Authentication
All API requests require a Bearer token. Generate an API key from your dashboard under API & Webhooks → API Keys.
curl -H "Authorization: Bearer dp_live_xxxxx" \
https://roleupgrade.com/api/v1/packagesKeep your keys secure
dp_live_ and support permission scoping. Never share your API keys or commit them to public repositories.Rate Limiting
Standard rate limit is 60 requests per minute. Rate limit headers are returned on every response:
| Header | Description |
|---|---|
X-RateLimit-Limit | Max requests per window |
X-RateLimit-Remaining | Remaining requests |
X-RateLimit-Reset | Window reset time (epoch seconds) |
Base URL
https://roleupgrade.com/api/v1Packages
GET/api/v1/packages
List all active packages for the authenticated seller.
Response
{
"packages": [
{
"_id": "abc123",
"name": "VIP Access",
"slug": "vip-access",
"priceAmount": 999,
"currency": "usd",
"billingInterval": "monthly",
"isActive": true
}
]
}Customers
GET/api/v1/customers
List customers with optional ?limit= and ?cursor= pagination.
Response
{
"customers": [
{
"_id": "user123",
"discordId": "123456789012345678",
"discordUsername": "john_doe"
}
],
"cursor": "next_page_token"
}Subscriptions
GET/api/v1/subscriptions
List all subscriptions. Supports filters:
?status=active?packageId=abc123
POST/api/v1/subscriptions
Create a manual subscription (e.g., for imported or comped users).
Request Body
{
"discordUserId": "123456789012345678",
"packageId": "abc123",
"status": "active"
}Response
{
"subscriptionId": "sub_xyz"
}PATCH/api/v1/subscriptions
Update a subscription. Pass ?id=sub_xyz or include in body.
DELETE/api/v1/subscriptions
Cancel/delete a subscription. Pass ?id=sub_xyz.
Analytics
GET/api/v1/analytics/revenue
Revenue analytics including totals, MRR, and period breakdowns.
GET/api/v1/analytics/subscribers
Subscriber counts by status, growth trends, and churn data.
Promotions
GET/api/v1/promotions
List all promotions/coupon codes.
POST/api/v1/promotions
Create a new promotion.
Request Body
{
"code": "SAVE20",
"discountType": "percentage",
"discountValue": 20,
"duration": "once",
"maxRedemptions": 100
}Health Check
GET/api/v1/health
Returns API status. No authentication required.
{ "status": "ok", "timestamp": 1708000000000 }Error Responses
All errors follow a consistent format:
{
"error": "Description of the error",
"code": "INVALID_REQUEST"
}| Status | Description |
|---|---|
400 | Invalid request parameters |
401 | Missing or invalid API key |
403 | Insufficient permissions |
404 | Resource not found |
429 | Rate limit exceeded |
500 | Internal server error |