Subscription API Reference

Complete API reference for the subscription management system, including all endpoints for plans, subscriptions, and billing operations.

Authentication

All subscription API endpoints require authentication. Include the user session in your requests.

Subscription Plans

Get All Plans

Retrieve all active subscription plans.

GET /api/subscriptions/plans

Response:

{
  "status": "success",
  "data": [
    {
      "id": "plan_123",
      "name": "starter",
      "displayName": "Starter Plan",
      "description": "Perfect for small teams",
      "monthlyPrice": "9.99",
      "annualPrice": "99.99",
      "stripePriceIdMonthly": "price_starter_monthly",
      "stripePriceIdAnnual": "price_starter_annual",
      "features": ["Basic analytics", "Email support"],
      "limits": {
        "seats": 5,
        "storage": 10,
        "apiCalls": 1000,
        "projects": 3
      },
      "isActive": true,
      "sortOrder": 1,
      "isPopular": false,
      "trialDays": 14,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Plan (Admin)

Create a new subscription plan.

POST /api/subscriptions/plans/create

Request Body:

{
  "name": "premium",
  "displayName": "Premium Plan",
  "description": "Advanced features for power users",
  "monthlyPrice": 49.99,
  "annualPrice": 499.99,
  "stripePriceIdMonthly": "price_premium_monthly",
  "stripePriceIdAnnual": "price_premium_annual",
  "features": ["Advanced analytics", "Priority support"],
  "limits": {
    "seats": 50,
    "storage": 500,
    "apiCalls": 50000,
    "projects": 25
  },
  "isActive": true,
  "sortOrder": 2,
  "isPopular": false,
  "trialDays": 14
}

Update Plan (Admin)

Update an existing subscription plan.

PUT /api/subscriptions/plans/{planId}

Delete Plan (Admin)

Delete a subscription plan.

DELETE /api/subscriptions/plans/{planId}

Organization Subscriptions

Get Organization Subscriptions

Retrieve subscriptions for an organization.

GET /api/organizations/{organizationId}/subscriptions

Query Parameters:

• status (optional) - Filter by subscription status
• plan (optional) - Filter by plan name
• stripeCustomerId (optional) - Filter by Stripe customer ID

Create Organization Subscription

Create a new subscription for an organization.

POST /api/organizations/{organizationId}/subscriptions

Request Body:

{
  "plan": "pro",
  "referenceId": "org_456",
  "status": "trialing",
  "seats": 10,
  "trialStart": "2024-01-01T00:00:00Z",
  "trialEnd": "2024-01-15T00:00:00Z",
  "billingInterval": "monthly"
}

Update Subscription

Update an existing subscription.

PUT /api/organizations/{organizationId}/subscriptions/{subscriptionId}

Delete Subscription

Cancel a subscription.

DELETE /api/organizations/{organizationId}/subscriptions/{subscriptionId}

Checkout and Billing

Create Checkout Session

Create a Stripe checkout session.

POST /api/subscriptions/checkout

Request Body:

{
  "planId": "plan_pro_123",
  "billingInterval": "monthly",
  "organizationId": "org_456",
  "successUrl": "https://yourapp.com/success",
  "cancelUrl": "https://yourapp.com/cancel",
  "seats": 10
}

Response:

{
  "status": "success",
  "data": {
    "sessionId": "cs_stripe_session_123",
    "url": "https://checkout.stripe.com/pay/cs_stripe_session_123"
  }
}

Access Billing Portal

Create a billing portal session.

POST /api/subscriptions/billing-portal

Request Body:

{
  "organizationId": "org_456",
  "returnUrl": "https://yourapp.com/billing"
}

Response:

{
  "status": "success",
  "data": {
    "url": "https://billing.stripe.com/session/xyz123"
  }
}

Webhooks

Stripe Webhook Handler

Processes Stripe webhook events.

POST /api/webhooks/stripe

Headers:

• stripe-signature - Stripe webhook signature

Supported Events:

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.payment_succeeded
• invoice.payment_failed

Error Responses

All endpoints return consistent error responses:

{
  "statusCode": 400,
  "message": "Validation error",
  "data": {
    // Validation details
  }
}

Common Status Codes:

• 400 - Bad Request (validation errors)
• 401 - Unauthorized (not authenticated)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found (resource doesn't exist)
• 409 - Conflict (duplicate resource)
• 500 - Internal Server Error

Rate Limiting

API endpoints are rate limited to prevent abuse:

• Checkout endpoints: 10 requests per minute per user
• Plan management: 100 requests per minute per user
• Subscription queries: 1000 requests per minute per organization

SDK Examples

Frontend Usage

// Get subscription plans
const plans = await $fetch('/api/subscriptions/plans')

// Create checkout session
const checkout = await $fetch('/api/subscriptions/checkout', {
  method: 'POST',
  body: {
    planId: 'plan_123',
    billingInterval: 'monthly',
    organizationId: 'org_456'
  }
})

// Redirect to checkout
window.location.href = checkout.data.url

Backend Usage

// Check subscription access
const hasAccess = await userHasSubscriptionAccess(
  userId,
  organizationId,
  'write'
)

// Get organization subscription
const subscription = await getAllSubscriptions({
  referenceId: organizationId
})

// Enforce plan limits
if (subscription.planDetails.limits.seats) {
  const currentSeats = await getOrganizationMemberCount(organizationId)
  if (currentSeats >= subscription.planDetails.limits.seats) {
    throw new Error('Seat limit exceeded')
  }
}