Skip to main content

​
Overview

Plans are the foundational building blocks of your pricing structure in FlexPrice. Each plan represents a pricing model that can be assigned to customers through subscriptions. Plans contain prices, features, and metadata that define what customers receive and how they’re charged.

​
Plan Structure

​
Core Fields

​
id
string
required
Unique identifier for the plan (max 50 characters)
​
name
string
required
Display name of the plan (max 255 characters)
​
lookup_key
string
Human-readable identifier for API lookups (max 255 characters). Must be unique within tenant and environment.
​
description
text
Detailed description of what the plan includes
​
display_order
integer
default:"0"
Order in which plans should be displayed in UI (lower numbers appear first)
​
metadata
object
Custom key-value pairs for storing additional plan information
​
status
string
Plan status: draft or published. Only published plans can be used in subscriptions.

​
Environment Scoping

All plans are scoped to a specific tenant and environment, allowing you to:
  • Test pricing changes in development/staging before production
  • Maintain different pricing across multiple products or regions
  • Keep customer data isolated
Example Plan
{
  "id": "plan_abc123",
  "name": "Professional Plan",
  "lookup_key": "professional",
  "description": "Full-featured plan for growing teams",
  "display_order": 2,
  "environment_id": "env_prod",
  "tenant_id": "tenant_xyz",
  "status": "published",
  "metadata": {
    "category": "business",
    "recommended": "true"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
Plan Types

Plans can be structured in various ways depending on your business model:
Plans that charge based on the number of users or seats.
Seat-Based Plan
{
  "name": "Team Plan",
  "lookup_key": "team",
  "description": "$50 per user per month",
  "prices": [
    {
      "type": "FIXED",
      "billing_model": "FLAT_FEE",
      "billing_cadence": "RECURRING",
      "billing_period": "MONTHLY",
      "billing_period_count": 1,
      "amount": "50.00",
      "currency": "usd"
    }
  ]
}
Key Characteristics:
  • Price type: FIXED
  • Billing model: FLAT_FEE
  • Quantity represents number of seats
  • Common in SaaS applications

​
Working with Plans

​
Creating Plans

When creating a plan, consider:
Use names that clearly communicate value:
  • Good: “Professional”, “Enterprise”, “Pay As You Go”
  • Avoid: “Plan A”, “Option 2”, “Package X”
Set lookup_key for programmatic access:
{
  "name": "Professional Plan",
  "lookup_key": "professional"
}
Control how plans appear in your pricing page:
[
  {"name": "Starter", "display_order": 1},
  {"name": "Professional", "display_order": 2},
  {"name": "Enterprise", "display_order": 3}
]
Store additional business logic in metadata:
{
  "metadata": {
    "tier": "premium",
    "support_level": "priority",
    "onboarding_included": "true",
    "contract_required": "false"
  }
}
Plans start in draft status:
  • Test configuration without affecting customers
  • Validate prices and features
  • Publish only when ready for production use
{
  "status": "draft"  // Change to "published" when ready
}

​
Plan Lifecycle

1

Create as Draft

New plans are created with status: "draft". They’re not available for subscriptions yet.
2

Configure Prices

Add one or more prices to the plan. Plans can have multiple prices with different billing periods.
3

Associate Features

Link features to define what capabilities the plan includes (optional).
4

Publish

Change status to published to make the plan available for subscriptions.
5

Archive (Future)

Plans with active subscriptions cannot be deleted but can be hidden from new purchases.

​
Best Practices

Unique Lookup Keys: The lookup_key must be unique within your tenant and environment when status is published. Use descriptive keys like starter, professional, or enterprise.
Don’t Delete Active Plans: If a plan has active subscriptions, removing it can break customer billing. Instead, mark it as unavailable for new sign-ups using metadata.

Keep it Simple

Start with 2-3 clear plan tiers. You can add complexity later based on customer needs.

Consistent Billing Periods

Offer each plan in monthly and annual variants rather than mixing billing periods within a single plan.

Test in Staging

Use separate environments to test pricing changes before affecting production customers.

Version with Metadata

Use metadata to track plan versions: {"version": "2.0", "deprecated": "false"}

Prices

Configure pricing details for your plans

Features

Define feature access and limits per plan

Add-ons

Create optional add-ons for your plans

Subscriptions

Learn how plans are assigned to customers