Lumen Documentation

The Plans API allows you to create, manage, and configure subscription plans for your application. Plans can include features, pricing, and integration with pricing tables.

Overview

Plans represent subscription tiers that customers can subscribe to. Each plan can have:

Features: Specific capabilities or limits
Pricing: Monthly/yearly pricing with usage-based components
Versioning: Plans support versioning for changes over time
Pricing Table Integration: Automatic display in pricing tables

Authentication

All API requests require authentication via merchant credentials.

Endpoints

Get All Plans

Get all plans for the authenticated merchant.

GET https://api.getlumen.dev/v1/plans

Query Parameters

Parameter	Type	Description
`includeFeatures`	boolean	Include associated features in response
`includePrices`	boolean	Include pricing information in response
`includeTrials`	boolean	Include trial plans in response

Response

{
  "plans": [
    {
      "id": "plan_123",
      "stablePlanId": "starter_plan",
      "versionNumber": 1,
      "planName": "Starter Plan",
      "planDescription": "Perfect for getting started",
      "merchantId": "merchant_123",
      "isVisibleInPricingTable": true,
      "isEnterprisePlan": false,
      "buttonText": "Get Started",
      "enterpriseRedirectUrl": null,
      "createdAt": "2024-01-01T00:00:00Z",
      "features": [
        {
          "id": "feature_123",
          "slug": "api_calls",
          "displayName": "API Calls",
          "featureType": "number",
          "featureValue": "1000"
        }
      ]
    }
  ]
}

Get Plan by ID

Get a specific plan by its ID or stable ID.

GET https://api.getlumen.dev/v1/plans/{id}

Parameters

Parameter	Type	Description
`id`	string	Plan ID or stable plan ID

Query Parameters

Parameter	Type	Description
`includeFeatures`	boolean	Include associated features
`isStableId`	boolean	Treat ID parameter as stable ID

Response

Same structure as the plans array above, but returns a single plan.

Create Plan

Create a new subscription plan with optional features and pricing.

POST https://api.getlumen.dev/v1/plans

Request Body

{
  "planName": "Professional Plan",
  "planDescription": "For growing businesses",
  "currency": "USD",
  "monthlyPrice": 2900,
  "yearlyPrice": 2400,
  "hasYearlyPrice": true,
  "showInPricingTable": true,
  "isEnterprisePlan": false,
  "newFeatures": [
    {
      "featureName": "API Calls",
      "slug": "api_calls",
      "eventName": "api_call",
      "isUsageBased": true,
      "usagePricePerUnit": 10,
      "hasCreditAllowance": true,
      "creditAllowanceAmount": 10000,
      "creditAllowanceRenewal": "monthly"
    },
    {
      "featureName": "Premium Support",
      "slug": "premium_support",
      "isUsageBased": false
    }
  ],
  "featureIds": ["existing_feature_id"],
  "commitMessage": "Added professional plan with enhanced features"
}

Request Fields

Field	Type	Required	Description
`planName`	string	✓	Display name of the plan
`planDescription`	string		Plan description
`currency`	string		Currency code (defaults to merchant default)
`monthlyPrice`	number		Monthly price in cents
`yearlyPrice`	number		Yearly price in cents
`hasYearlyPrice`	boolean		Whether plan offers yearly pricing
`isSeatBased`	boolean		Enable seat-based per-unit pricing
`minSeats`	number		Minimum seats when billing immediately
`billImmediately`	boolean		Bill fixed/per-seat components upfront
`showInPricingTable`	boolean		Add to pricing table automatically
`isEnterprisePlan`	boolean		Mark as enterprise plan
`enterpriseButtonText`	string		Custom button text for enterprise
`enterpriseRedirectUrl`	string		Redirect URL for enterprise plans
`newFeatures`	array		Features to create and associate
`featureIds`	array		Existing feature IDs to associate
`commitMessage`	string		Version commit message
`trial`	object		Free trial configuration

New Features Schema

Field	Type	Required	Description
`featureName`	string	✓	Display name
`slug`	string	✓	Unique identifier
`eventName`	string		Event name for usage tracking
`isUsageBased`	boolean	✓	Whether feature tracks usage
`usagePricePerUnit`	number		Price per usage unit in cents
`hasCreditAllowance`	boolean		Include credit allowance
`creditAllowanceAmount`	number		Credit amount
`creditAllowanceRenewal`	enum		`monthly`, `yearly`, or `none`
`existingFeatureId`	string		ID of existing feature to configure
`trial.enabled`	boolean		Enable or disable free trial
`trial.days`	number		Trial length in days (when enabled)
`trial.creditOverrides`	array		Optional per-feature trial credits

Response

{
  "plans": [
    {
      "id": "plan_456",
      "stablePlanId": "professional_plan",
      "versionNumber": 1,
      "planName": "Professional Plan",
      "planDescription": "For growing businesses",
      "merchantId": "merchant_123",
      "isVisibleInPricingTable": true,
      "isEnterprisePlan": false,
      "buttonText": "Get Started",
      "features": [
        {
          "id": "feature_456",
          "slug": "api_calls",
          "displayName": "API Calls",
          "featureType": "number",
          "featureValue": "usage_based"
        }
      ],
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Update Plan

Create a new version of an existing plan with updated configuration.

POST https://api.getlumen.dev/v1/plans/{id}

Parameters

Parameter	Type	Description
`id`	string	Plan ID or stable plan ID

Query Parameters

Parameter	Type	Description
`isStableId`	boolean	Treat ID as stable plan ID

Request Body

{
  "planName": "Professional Plan v2",
  "planDescription": "Updated professional plan",
  "priceIds": ["price_123", "price_456"],
  "featureIds": ["feature_123", "feature_456"],
  "commitMessage": "Updated plan with new pricing"
}

Request Fields

Field	Type	Description
`planName`	string	Updated plan name
`planDescription`	string	Updated description
`priceIds`	array	Price IDs to associate with new version
`featureIds`	array	Feature IDs to associate with new version
`commitMessage`	string	Version commit message

Note: If priceIds or featureIds are not provided, the existing associations will be cloned to the new version.

Response

Returns the new plan version with the same structure as the create response.

Intelligent Plan Edit

Performs an in-place edit when safe (metadata-only or feature rename-only), otherwise creates a new version of the plan.

POST https://api.getlumen.dev/v1/plans/{id}/edit

Request Body (subset)

{
  "planName": "Pro Plan",
  "planDescription": "Updated copy",
  "features": [
    { "featureName": "API Calls", "slug": "api_calls", "isUsageBased": true, "usagePricePerUnit": 10 }
  ],
  "monthlyPrice": 2900,
  "yearlyPrice": 2400,
  "hasYearlyPrice": true,
  "isSeatBased": false,
  "showInPricingTable": true,
  "trial": { "enabled": true, "days": 14 }
}

Response

Returns the updated plan. If a new version was required, the response includes the new version data.

Migrate Subscribers Between Plan Versions

Migrate or schedule migrations from one version of a plan to another, with explicit price mapping.

POST https://api.getlumen.dev/v1/plans/{stablePlanId}/migrate

Request Body

{
  "strategy": "next_billing_cycle",
  "fromVersion": 1,
  "toVersion": 2,
  "priceMapping": { "price_old": "price_new" }
}

Response

{ "success": true, "scheduledCount": 123, "message": "Scheduled migration..." }

Compare Plan Versions

Analyze differences between two versions and get a recommended migration strategy.

GET https://api.getlumen.dev/v1/plans/{stablePlanId}/compare?fromVersion=1&toVersion=2

Response

{
  "migrationAnalysis": {
    "hasPriceChanges": false,
    "hasFeatureChanges": true,
    "hasNumericFeatureChanges": false,
    "recommendedStrategy": "immediate"
  }
}

Get Scheduled Migrations (from a plan version)

GET https://api.getlumen.dev/v1/plans/{planId}/scheduled-migrations

Response

{ "scheduledMigrations": [ /* array of scheduled changes */ ] }

Get Incoming Migrations (to a plan version)

GET https://api.getlumen.dev/v1/plans/{planId}/incoming-migrations

Response

{ "incomingMigrations": [ /* array of incoming changes */ ] }

Delete Plan

Soft delete a plan and its associations.

DELETE https://api.getlumen.dev/v1/plans/{id}

Parameters

Parameter	Type	Description
`id`	string	Plan ID to delete

Response

{
  "success": true,
  "message": "Plan and associated features and pricing table associations deleted successfully"
}

Toggle Pricing Table Visibility

Add or remove a plan from pricing tables.

POST https://api.getlumen.dev/v1/plans/{id}/toggle-pricing-table-visibility

Parameters

Parameter	Type	Description
`id`	string	Plan ID

Request Body

{
  "isVisible": true
}

Response

{
  "success": true,
  "message": "Plan added to pricing table successfully",
  "plan": {
    "id": "plan_123",
    "isVisibleInPricingTable": true
    // ... full plan object
  }
}

Examples

Creating a Basic Plan

curl -X POST https://api.getlumen.dev/v1/plans \
  -H "Content-Type: application/json" \
  -d '{
    "planName": "Basic Plan",
    "planDescription": "Essential features for small teams",
    "monthlyPrice": 999,
    "showInPricingTable": true
  }'

Creating a Plan with Usage-Based Features

curl -X POST https://api.getlumen.dev/v1/plans \
  -H "Content-Type: application/json" \
  -d '{
    "planName": "Professional Plan",
    "planDescription": "Advanced features with usage tracking",
    "monthlyPrice": 2900,
    "yearlyPrice": 2400,
    "hasYearlyPrice": true,
    "showInPricingTable": true,
    "newFeatures": [
      {
        "featureName": "API Calls",
        "slug": "api_calls",
        "eventName": "api_call",
        "isUsageBased": true,
        "usagePricePerUnit": 10,
        "hasCreditAllowance": true,
        "creditAllowanceAmount": 10000,
        "creditAllowanceRenewal": "monthly"
      }
    ]
  }'

Creating an Enterprise Plan

curl -X POST https://api.getlumen.dev/v1/plans \
  -H "Content-Type: application/json" \
  -d '{
    "planName": "Enterprise Plan",
    "planDescription": "Custom solutions for large organizations",
    "isEnterprisePlan": true,
    "enterpriseButtonText": "Contact Sales",
    "enterpriseRedirectUrl": "https://example.com/contact",
    "showInPricingTable": true,
    "featureIds": ["feature_1", "feature_2", "feature_3"]
  }'

Updating a Plan

curl -X POST https://api.getlumen.dev/v1/plans/plan_123 \
  -H "Content-Type: application/json" \
  -d '{
    "planName": "Updated Basic Plan",
    "planDescription": "Enhanced basic plan with more features",
    "featureIds": ["feature_1", "feature_2", "feature_3"],
    "commitMessage": "Added additional features to basic plan"
  }'

Error Responses

All endpoints may return these error responses:

400 Bad Request

{
  "error": "One or more feature IDs are invalid or do not belong to this merchant"
}

404 Not Found

{
  "error": "Plan not found or access denied"
}

500 Internal Server Error

{
  "error": "Failed to create plan"
}

{
  "error": "Failed to process plan migration"
}

Important Notes

Plan Versioning

Plans support versioning for tracking changes over time
Each update creates a new version with an incremented versionNumber
The stablePlanId remains constant across versions
Use commitMessage to document changes between versions

Pricing Integration

Plans can automatically integrate with pricing tables
Set showInPricingTable: true to add to the default pricing table
Plans are ordered by price (lowest to highest) in pricing tables
Enterprise plans appear last regardless of pricing

Feature Management

Features can be created inline with newFeatures or referenced by ID with featureIds
Usage-based features support automatic credit allowances
Credit allowances can renew monthly, yearly, or be one-time grants

Currency Handling

Prices are specified in cents (e.g., 2900 = $29.00)
Currency defaults to merchant's default currency if not specified
Both monthly and yearly pricing can be configured

Enterprise Plans

Enterprise plans don't require pricing configuration
They can have custom button text and redirect URLs
Useful for custom pricing or sales-driven processes

Plans API

On this page