Update Plan (v1)

Update a subscription plan.

Method & Path

PATCH /v1/admin/plans/:planId

Description

Updates an existing subscription plan. At least one field must be provided.

Authentication

Required: Admin authentication with plans.manage permission.

Path Parameters

Parameter	Type	Required	Description
planId	string	Yes	The plan ID

Request Body

At least one field must be provided. All fields are optional.

{
  "name": "Updated Pro Plan",
  "slug": "updated-pro-plan",
  "description": "Updated description",
  "isActive": true,
  "sortOrder": 2,
  "trialPeriodDays": 30,
  "pricePeriods": [
    {
      "period": "monthly",
      "amountCents": 14900,
      "currencyCode": "USD"
    },
    {
      "period": "annual",
      "amountCents": 149000,
      "currencyCode": "USD"
    }
  ],
  "features": [
    {
      "key": "new-feature",
      "translations": [
        {
          "locale": "en",
          "label": "New Feature",
          "description": "Description of new feature"
        }
      ]
    }
  ],
  "flags": [
    {
      "key": "max-staff",
      "value": "100"
    }
  ],
  "translations": [
    {
      "locale": "en",
      "name": "Updated Pro Plan",
      "description": "Updated description"
    }
  ]
}

Request Body Fields

All fields are optional, but at least one must be provided:

Field	Type	Description
name	string	Plan name (1-120 characters)
slug	string	Unique plan identifier (2-50 characters)
description	string|null	Plan description (max 500 characters, null to clear)
isActive	boolean	Whether plan is active
sortOrder	number	Sort order for display
trialPeriodDays	number|null	Trial period in days (null for no trial)
pricePeriods	array	Array of price periods (minimum 1 if provided)
features	array	Plan features array (max 50)
flags	array	Plan flags array (max 50)
translations	array	Localized plan information (minimum 1 if provided)

Note: When updating pricePeriods, all periods must be provided (cannot partially update). Each billing period can only be defined once.

Response 200 OK

{
  "plan": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Updated Pro Plan",
    "slug": "updated-pro-plan",
    "description": "Updated description",
    "isActive": true,
    "sortOrder": 2,
    "trialPeriodDays": 30,
    "pricePeriods": [
      {
        "period": "monthly",
        "amountCents": 14900,
        "currencyCode": "USD"
      },
      {
        "period": "annual",
        "amountCents": 149000,
        "currencyCode": "USD"
      }
    ],
    "features": [
      {
        "key": "new-feature",
        "translations": [
          {
            "locale": "en",
            "label": "New Feature",
            "description": "Description of new feature"
          }
        ]
      }
    ],
    "flags": [
      {
        "key": "max-staff",
        "value": "100"
      }
    ],
    "translations": [
      {
        "locale": "en",
        "name": "Updated Pro Plan",
        "description": "Updated description"
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:45:00.000Z"
  }
}

Common Errors

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