Create Plan (v1)

Create a new subscription plan.

Method & Path

POST /v1/admin/plans

Description

Creates a new subscription plan with specified features and pricing.

Authentication

Required: Admin authentication with plans.manage permission.

Request Body

{
  "name": "Pro Plan",
  "slug": "pro-plan",
  "description": "Professional plan with advanced features",
  "isActive": true,
  "sortOrder": 1,
  "trialPeriodDays": 14,
  "pricePeriods": [
    {
      "period": "monthly",
      "amountCents": 9900,
      "currencyCode": "USD"
    },
    {
      "period": "quarterly",
      "amountCents": 27000,
      "currencyCode": "USD"
    },
    {
      "period": "annual",
      "amountCents": 99000,
      "currencyCode": "USD"
    }
  ],
  "features": [
    {
      "key": "unlimited-clients",
      "translations": [
        {
          "locale": "en",
          "label": "Unlimited Clients",
          "description": "Add as many clients as you need"
        }
      ]
    }
  ],
  "flags": [],
  "translations": [
    {
      "locale": "en",
      "name": "Pro Plan",
      "description": "Professional plan with advanced features"
    }
  ]
}

Request Body Fields

Field	Type	Required	Description
name	string	Yes	Plan name (1-120 characters)
slug	string	Yes	Unique plan identifier (2-50 characters, lowercase, alphanumeric with hyphens)
description	string	No	Plan description (max 500 characters)
isActive	boolean	No	Whether plan is active (default: true)
sortOrder	number	No	Sort order for display (default: 0)
trialPeriodDays	number|null	No	Trial period in days (0 or more, null for no trial)
pricePeriods	array	Yes	Array of price periods (minimum 1 required)
pricePeriods[].period	enum	Yes	Billing period: "monthly", "quarterly", "semiannual", or "annual"
pricePeriods[].amountCents	number	Yes	Price in cents (0 to 1,000,000,000)
pricePeriods[].currencyCode	string	Yes	ISO 4217 currency code (3 uppercase letters, e.g., "USD", "ILS", "JOD", "EUR")
features	array	No	Plan features array (max 50)
flags	array	No	Plan flags array (max 50)
translations	array	Yes	Localized plan names and descriptions (minimum 1 required)

Note: Each billing period can only be defined once per plan. All periods must have the same currency code.

Response 201 Created

{
  "plan": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Pro Plan",
    "slug": "pro-plan",
    "description": "Professional plan with advanced features",
    "isActive": true,
    "sortOrder": 1,
    "trialPeriodDays": 14,
    "pricePeriods": [
      {
        "period": "monthly",
        "amountCents": 9900,
        "currencyCode": "USD"
      },
      {
        "period": "quarterly",
        "amountCents": 27000,
        "currencyCode": "USD"
      },
      {
        "period": "annual",
        "amountCents": 99000,
        "currencyCode": "USD"
      }
    ],
    "features": [
      {
        "key": "unlimited-clients",
        "translations": [
          {
            "locale": "en",
            "label": "Unlimited Clients",
            "description": "Add as many clients as you need"
          }
        ]
      }
    ],
    "flags": [],
    "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"
  }
}

Common Errors

• 401 Unauthorized: Missing or invalid admin authentication token
• 403 Forbidden: Insufficient permissions
• 400 Bad Request: Invalid request body
• 500 Internal Server Error: Server error