Plans API

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 /api/plans

Query Parameters

Parameter	Type	Description
`includeFeatures`	boolean	Include associated features in response
`includePrices`	boolean	Include pricing information 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 /api/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 /api/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
`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

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

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 /api/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.

Delete Plan

Soft delete a plan and its associations.

DELETE /api/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 /api/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 /api/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 /api/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 /api/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 /api/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"
}

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