|
|-----------------|----------|-----------------------------------------------------------------------------|
| Cookie | Yes | Contains the session token used by @/lib/auth to validate admin privileges |
| Authorization | Optional | Bearer token alternative, depending on session configuration |
Authentication Behavior
The route handler calls auth() from @/lib/auth and validates that the resolved session contains a user object with role === 'ADMIN'. If the session is missing, expired, or lacks admin privileges, the request is immediately terminated with a 403 status.
Success Response (200 OK)
Returns a JSON object containing aggregated subscription metrics. All numeric values are integers or floats representing counts or currency amounts.
{
"totalSubscribers": 142,
"activeSubscriptions": 156,
"canceledSubscriptions": 38,
"mrr": 4527,
"arr": 54324,
"byPlan": [
{ "plan": "BUILDER", "count": 89, "revenue": 801 },
{ "plan": "PRO", "count": 45, "revenue": 1305 },
{ "plan": "ENTERPRISE", "count": 22, "revenue": 2178 }
],
"recentSubscriptions": []
}
Field Descriptions
| Field | Type | Description |
|---|
totalSubscribers | number | Count of users with a non-FREE planType and ACTIVE subscription status |
activeSubscriptions | number | Total users with subscriptionStatus === 'ACTIVE' |
canceledSubscriptions | number | Total users with subscriptionStatus === 'INACTIVE' |
mrr | number | Monthly Recurring Revenue calculated from active users |
arr | number | Annual Recurring Revenue (mrr * 12) |
byPlan | array | Breakdown of active subscriptions grouped by plan type |
recentSubscriptions | array | Placeholder array; currently hardcoded to [] |
Error Responses
| Status Code | Response Body | Condition |
|---|
403 | { "error": "Forbidden" } | Missing session, invalid session, or user role is not ADMIN |
500 | { "error": "Internal server error" } | Database query failure, Prisma connection error, or unexpected runtime exception |
Usage Example
Below is a curl command demonstrating how to call the endpoint. Replace <SESSION_COOKIE> with a valid admin session cookie obtained through your application's authentication flow.
curl -X GET "https://your-domain.com/api/admin/subscriptions" \
-H "Cookie: <SESSION_COOKIE>" \
-H "Accept: application/json"
Expected Output:
{
"totalSubscribers": 142,
"activeSubscriptions": 156,
"canceledSubscriptions": 38,
"mrr": 4527,
"arr": 54324,
"byPlan": [
{ "plan": "BUILDER", "count": 89, "revenue": 801 },
{ "plan": "PRO", "count": 45, "revenue": 1305 },
{ "plan": "ENTERPRISE", "count": 22, "revenue": 2178 }
],
"recentSubscriptions": []
}
Common Pitfalls
-
Authentication Metadata Mismatch
The route metadata may list this endpoint as public, but the source code explicitly enforces admin role validation. Developers attempting to call this endpoint without a valid admin session will receive a 403 Forbidden response. Always ensure the request carries a properly authenticated session cookie or token before integration.
-
Hardcoded Pricing Logic
MRR and ARR calculations rely on a static planPrices mapping (FREE: 0, BUILDER: 9, PRO: 29, ENTERPRISE: 99). These values are placeholders and do not reflect actual payment processor rates, discounts, or regional pricing. Until Stripe or Paddle integration is completed, treat these financial metrics as approximate indicators rather than production-grade billing data.
-
Empty recentSubscriptions Array
The response includes a recentSubscriptions field that is currently hardcoded to an empty array. This is a structural placeholder for future webhook-driven activity feeds. Do not build UI components or downstream logic that depend on this field containing real-time subscription events, as it will not populate until the payment integration is finalized.
This endpoint is designed to operate within the broader administrative API ecosystem. While it focuses exclusively on aggregated subscription metrics, it is typically paired with:
- User Management Routes (
/api/admin/users/*): For retrieving detailed user profiles, plan assignments, and account statuses that feed into the subscription calculations.
- Billing Webhook Handlers (
/api/billing/webhooks): For processing payment provider events that update subscriptionStatus and planType in the database, which this endpoint subsequently aggregates.
- Dashboard Analytics Endpoints (
/api/admin/analytics/*): For complementary metrics such as user growth, churn rates, and feature usage that provide context to the financial data returned by this route.
When building admin dashboards or internal reporting tools, combine this endpoint with user-level queries to drill down from macro metrics to individual account details. Always respect rate limits and session expiration policies when polling this route in automated monitoring scripts.
