Subscription Plans

Subscription plans define the available service tiers in your SaaS application. Each plan includes pricing, features, limits, and Stripe integration details.

Plan Structure

Core Properties

interface SubscriptionPlan {
  id: string                    // Unique plan identifier
  name: string                  // Internal name (e.g., 'starter', 'pro')
  displayName: string          // User-facing name (e.g., 'Starter Plan')
  description?: string         // Plan description
  monthlyPrice: number         // Monthly price in dollars
  annualPrice?: number         // Annual price in dollars (optional)
  stripePriceIdMonthly: string // Stripe monthly price ID
  stripePriceIdAnnual?: string // Stripe annual price ID (optional)
  features: string[]           // List of included features
  limits: PlanLimits          // Usage limits
  isActive: boolean           // Whether plan is available
  sortOrder: number           // Display order
  isPopular: boolean          // Highlight as popular choice
  trialDays: number           // Free trial period in days
}

Plan Limits

Plans can define various usage limits:

interface PlanLimits {
  seats?: number | null       // Team member limit (null = unlimited)
  storage?: number | null     // Storage limit in GB (null = unlimited)
  apiCalls?: number | null    // Monthly API call limit (null = unlimited)
  projects?: number | null    // Project limit (null = unlimited)
  [key: string]: number | null | undefined // Custom limits
}

Plan Management API

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 getting started",
      "monthlyPrice": "9.99",
      "annualPrice": "99.99",
      "stripePriceIdMonthly": "price_starter_monthly",
      "stripePriceIdAnnual": "price_starter_annual",
      "features": [
        "Up to 5 team members",
        "Basic analytics",
        "Email support"
      ],
      "limits": {
        "seats": 5,
        "storage": 10,
        "apiCalls": 1000,
        "projects": 3
      },
      "isActive": true,
      "sortOrder": 1,
      "isPopular": false,
      "trialDays": 14
    }
  ]
}

Create Plan (Admin Only)

Create a new subscription plan, the plan will be created inside your Stripe account as well as in the database. They will keep in sync.

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": [
    "Up to 50 team members",
    "Advanced analytics",
    "Priority support",
    "Premium integrations"
  ],
  "limits": {
    "seats": 50,
    "storage": 500,
    "apiCalls": 50000,
    "projects": 25
  },
  "isActive": true,
  "sortOrder": 2,
  "isPopular": false,
  "trialDays": 14
}

Update Plan (Admin Only)

Update an existing subscription plan:

PUT /api/subscriptions/plans/{planId}

Request Body:

{
  "displayName": "Premium Plus Plan",
  "monthlyPrice": 59.99,
  "features": [
    "Up to 100 team members",
    "Advanced analytics",
    "24/7 support"
  ]
}

Delete Plan (Admin Only)

Delete a subscription pla, this will also delete the plan from Stripe. Stripe does not offer a way to delete prices so the only way is to archive it.

DELETE /api/subscriptions/plans/{planId}

Custom Plan Properties

You can extend plan limits with custom properties:

const customLimits = {
  seats: 10,
  storage: 50,
  apiCalls: 5000,
  projects: 5,
  // Custom limits
  customReports: 10,
  advancedIntegrations: 3,
  customDomains: 1
}

Best Practices

Plan Naming

• Use lowercase, hyphenated names for internal identifiers
• Provide clear, descriptive display names
• Include helpful descriptions for complex plans

Pricing Strategy

• Consider annual discounts (typically 15-20%)
• Use psychological pricing ($9.99 vs $10.00)
• Ensure pricing aligns with value proposition

Feature Organization

• List features in order of importance
• Use clear, benefit-focused language
• Avoid technical jargon in user-facing features

Limit Setting

• Use null for unlimited features
• Set reasonable defaults that encourage upgrades
• Consider usage patterns when setting limits

Integration with Stripe

Plans must be configured in both your application and Stripe:

1. Create Stripe Products for each plan
2. Create Stripe Prices for monthly/annual billing
3. Configure plan with Stripe price IDs
4. Test checkout flow before going live

See Stripe Integration for detailed setup instructions.