Plans
Update Plan (Create New Version)
Update a plan by creating a new version. Plans are immutable—updates always create a new version with an incremented versionNumber. If only cosmetic fields (planName, planDescription) are changed without new priceIds or featureIds, the update happens in-place. When priceIds or featureIds are provided, a new version is created, existing subscriptions can be migrated, and the stablePlanId remains constant across versions.
Authorization
bearerAuth AuthorizationBearer <token>
Use your secret API key as the bearer token
In: header
Path Parameters
id*string
Plan version ID (pln_) or stable plan ID (pln_stable_)
Query Parameters
isStableId?string
Set to true if updating by stable plan ID. The latest version will be used as the base.
Default
"false"Value in
"true" | "false"Request Body
application/json
planName?string
description?string
features?
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/plans/pln_stable_abc123" \ -H "Content-Type: application/json" \ -d '{ "planName": "Professional Plan", "planDescription": "Now with even more features!", "commitMessage": "Rebranding update" }'{
"plans": [
{
"id": "pln_01hrx9999new",
"stablePlanId": "pln_stable_abc123",
"merchantId": "mrc_01hptv3p6xj173pfv96pxd5pke",
"versionNumber": 3,
"planName": "Professional Plan",
"planDescription": "Now with even more features!",
"commitMessage": "Added premium analytics feature",
"isTrialPlan": false,
"createdAt": "2025-02-20T17:00:00.000Z",
"deletedAt": null
}
]
}{
"error": "One or more feature IDs are invalid or do not belong to this merchant"
}{
"error": "Plan not found or access denied"
}{
"error": "Failed to update plan",
"details": "Database transaction failed"
}