List Plans (v1)

Get all subscription plans.

Method & Path

GET /v1/admin/plans

Description

Retrieves all subscription plans available in the platform.

Authentication

Required: Admin authentication with plans.manage permission.

Response 200 OK

{
  "plans": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Basic Plan",
      "slug": "basic-plan",
      "description": "Basic plan for small businesses",
      "isActive": true,
      "sortOrder": 1,
      "trialPeriodDays": 14,
      "pricePeriods": [
        {
          "period": "monthly",
          "amountCents": 2999,
          "currencyCode": "USD"
        },
        {
          "period": "annual",
          "amountCents": 29990,
          "currencyCode": "USD"
        }
      ],
      "features": [],
      "flags": [],
      "translations": [
        {
          "locale": "en",
          "name": "Basic Plan",
          "description": "Basic plan for small businesses"
        }
      ],
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "name": "Pro Plan",
      "slug": "pro-plan",
      "description": "Professional plan with advanced features",
      "isActive": true,
      "sortOrder": 2,
      "trialPeriodDays": 14,
      "pricePeriods": [
        {
          "period": "monthly",
          "amountCents": 9900,
          "currencyCode": "USD"
        },
        {
          "period": "quarterly",
          "amountCents": 27000,
          "currencyCode": "USD"
        },
        {
          "period": "semiannual",
          "amountCents": 54000,
          "currencyCode": "USD"
        },
        {
          "period": "annual",
          "amountCents": 99000,
          "currencyCode": "USD"
        }
      ],
      "features": [
        {
          "key": "unlimited-clients",
          "translations": [
            {
              "locale": "en",
              "label": "Unlimited Clients"
            }
          ]
        }
      ],
      "flags": [
        {
          "key": "max-staff",
          "value": "50"
        }
      ],
      "translations": [
        {
          "locale": "en",
          "name": "Pro Plan",
          "description": "Professional plan with advanced features"
        }
      ],
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Response Fields

The response contains an array of plans, each with the following structure:

Field	Type	Description
id	string	Plan unique identifier
name	string	Plan name
slug	string	Plan unique slug
description	string|null	Plan description
isActive	boolean	Whether plan is active
sortOrder	number	Sort order for display
trialPeriodDays	number|null	Trial period in days
pricePeriods	array	Array of price periods with different billing cycles
pricePeriods[].period	string	Billing period: "monthly", "quarterly", "semiannual", or "annual"
pricePeriods[].amountCents	number	Price in cents
pricePeriods[].currencyCode	string	ISO 4217 currency code
features	array	Plan features with translations
flags	array	Plan configuration flags
translations	array	Localized plan information
createdAt	string	Creation timestamp (ISO 8601)
updatedAt	string	Last update timestamp (ISO 8601)

Note: Plans are returned sorted by sortOrder and isActive status.

Common Errors

• 401 Unauthorized: Missing or invalid admin authentication token
• 403 Forbidden: Insufficient permissions
• 500 Internal Server Error: Server error