Skip to main content

​
Overview

Add-ons are optional products that customers can purchase alongside their base plan. They extend plan functionality with additional features, capacity, or services without requiring a plan upgrade.

​
Add-on Structure

​
Core Fields

​
id
string
required
Unique identifier for the add-on (max 50 characters)
​
name
string
required
Display name of the add-on (max 255 characters)
​
lookup_key
string
required
Unique human-readable identifier for API lookups (max 255 characters)
​
description
text
Detailed description of what the add-on provides
​
type
enum
required
Add-on type:
  • onetime: Can only be purchased once per subscription
  • multiple_instance: Can be purchased multiple times (e.g., additional user packs)
​
metadata
object
Custom key-value pairs (stored as JSONB in PostgreSQL)
​
status
string
Add-on status: draft or published

​
Environment Context

Like plans, add-ons are scoped to a tenant and environment:
​
tenant_id
string
required
Tenant identifier
​
environment_id
string
required
Environment identifier (production, staging, development)
Example Add-on
{
  "id": "addon_extra_storage",
  "name": "Extra Storage Pack",
  "lookup_key": "extra_storage_100gb",
  "description": "Add 100 GB of storage to your plan",
  "type": "multiple_instance",
  "tenant_id": "tenant_xyz",
  "environment_id": "env_prod",
  "status": "published",
  "metadata": {
    "category": "storage",
    "popular": "true"
  },
  "created_at": "2024-02-01T12:00:00Z",
  "updated_at": "2024-02-01T12:00:00Z"
}

​
Add-on Types

Single instance per subscription. Customer can only purchase once.
One-Time Add-on
{
  "name": "Premium Support",
  "lookup_key": "premium_support",
  "type": "onetime",
  "description": "24/7 priority support with dedicated account manager",
  "metadata": {
    "category": "support"
  }
}
Use Cases:
  • Premium support packages
  • One-time setup services
  • Exclusive feature access
  • Custom integrations
Behavior:
  • Cannot be added twice to the same subscription
  • Typically toggles a feature or service on
  • Pricing via single price entity

​
Add-on Pricing

Add-ons have their own prices, configured separately from plan prices.

​
Pricing an Add-on

Create a price with entity_type: "ADDON":
Add-on Price
{
  "amount": "10.00",
  "currency": "usd",
  "type": "FIXED",
  "billing_model": "FLAT_FEE",
  "billing_cadence": "RECURRING",
  "billing_period": "MONTHLY",
  "billing_period_count": 1,
  "entity_type": "ADDON",
  "entity_id": "addon_extra_storage",
  "display_name": "Extra Storage (per 100 GB)"
}
Add-on prices follow the same structure as plan prices. See Prices for full configuration options.

​
Multiple Pricing Options

Offer different billing periods for the same add-on: 
{
  "entity_id": "addon_user_pack_5",
  "entity_type": "ADDON",
  "amount": "50.00",
  "currency": "usd",
  "billing_period": "MONTHLY",
  "display_name": "5 User Pack - Monthly"
}

​
Common Add-on Patterns

Increase limits or quotas beyond the base plan.
Storage Add-on
{
  "name": "Extra Storage - 100 GB",
  "lookup_key": "storage_100gb",
  "type": "multiple_instance",
  "description": "Add 100 GB to your storage quota",
  "metadata": {
    "capacity_increase": "100",
    "unit": "GB"
  }
}
Pricing:
  • $10/month per 100 GB pack
  • Customer can buy multiple packs
Implementation:
  • Track instances purchased
  • Calculate total: base plan storage + (addon instances × 100 GB)
Enable premium features not included in the base plan.
Advanced Analytics Add-on
{
  "name": "Advanced Analytics",
  "lookup_key": "advanced_analytics",
  "type": "onetime",
  "description": "Unlock custom reports, data exports, and dashboards",
  "metadata": {
    "unlocks_features": ["custom_reports", "data_export", "dashboards"]
  }
}
Pricing:
  • $49/month flat fee
  • One-time purchase
Implementation:
  • Check entitlements for add-on
  • Enable features if add-on is active
Professional services or enhanced support.
Onboarding Add-on
{
  "name": "Premium Onboarding",
  "lookup_key": "premium_onboarding",
  "type": "onetime",
  "description": "Dedicated onboarding specialist and custom setup",
  "metadata": {
    "service_type": "onboarding",
    "one_time_charge": "true"
  }
}
Pricing:
  • $499 one-time charge
  • Use billing_cadence: "ONETIME"
One-Time Service Price
{
  "entity_id": "addon_premium_onboarding",
  "entity_type": "ADDON",
  "amount": "499.00",
  "currency": "usd",
  "type": "FIXED",
  "billing_cadence": "ONETIME"
}
Prepaid bundles of usage credits.
SMS Credit Pack
{
  "name": "SMS Credit Pack - 10,000",
  "lookup_key": "sms_credits_10k",
  "type": "multiple_instance",
  "description": "10,000 SMS credits",
  "metadata": {
    "credit_amount": "10000",
    "credit_type": "sms"
  }
}
Pricing:
  • $100 per pack (10,000 credits)
  • One-time purchase, credits roll over
Implementation:
  • Grant credits to customer wallet
  • Deduct from wallet as usage occurs

​
Add-on Lifecycle

1

Create Add-on

Define the add-on with name, type, and metadata.
{
  "name": "Priority Support",
  "lookup_key": "priority_support",
  "type": "onetime",
  "status": "draft"
}
2

Configure Pricing

Create one or more prices for the add-on.
{
  "entity_type": "ADDON",
  "entity_id": "addon_priority_support",
  "amount": "99.00",
  "currency": "usd",
  "billing_period": "MONTHLY"
}
3

Publish

Change status to published to make available.
{"status": "published"}
4

Add to Subscription

Customers purchase add-ons when creating or updating subscriptions.
{
  "plan_id": "plan_professional",
  "addons": [
    {
      "addon_id": "addon_priority_support",
      "price_id": "price_support_monthly",
      "quantity": 1
    }
  ]
}
5

Manage Instances

For multiple_instance add-ons, customers can add more instances.
{
  "addons": [
    {
      "addon_id": "addon_user_pack_5",
      "quantity": 3  // 3 packs = 15 extra users
    }
  ]
}

​
Add-ons and Entitlements

Add-ons can grant feature entitlements just like plans.

​
Example: Storage Add-on

Base Plan Entitlement: 
{
  "plan_id": "plan_starter",
  "feature_id": "feat_storage",
  "limit": 10  // 10 GB base
}
Add-on Entitlement: 
{
  "addon_id": "addon_storage_100gb",
  "feature_id": "feat_storage",
  "limit": 100  // +100 GB per instance
}
Total for Customer:
  • Base plan: 10 GB
  • 2 instances of storage add-on: 2 × 100 GB = 200 GB
  • Total: 210 GB

​
Best Practices

Clear Add-on Scope

Make it obvious what the add-on provides:
  • “5 User Pack” (not “User Add-on”)
  • “100 GB Storage” (not “Extra Space”)
  • “Priority Support” (not “Premium Service”)

Match Billing Periods

Offer add-on billing periods that align with plan billing:
  • If plan is monthly, offer monthly add-on
  • If plan is annual, offer annual add-on pricing
  • Avoid mismatched billing cycles

Use Metadata Wisely

Store business logic in metadata:
{
  "metadata": {
    "category": "capacity",
    "increases_limit": "storage",
    "limit_increase_amount": "100",
    "recommended_for": "professional"
  }
}

Type Selection

Choose type based on use case:
  • onetime: Features, services, unique capabilities
  • multiple_instance: Capacity, quotas, scalable resources
Unique Lookup Keys: The lookup_key must be unique within your tenant and environment when status is published. FlexPrice enforces this with a database constraint.
Add-ons inherit the subscription’s billing period. If a customer switches from monthly to annual billing, add-on charges adjust accordingly.

​
Example Configurations

{
  "id": "addon_seats_10",
  "name": "10 Additional Seats",
  "lookup_key": "seats_10",
  "type": "multiple_instance",
  "description": "Add 10 user seats to your workspace",
  "status": "published",
  "metadata": {
    "category": "capacity",
    "seat_count": "10"
  },
  "prices": [
    {
      "amount": "100.00",
      "currency": "usd",
      "billing_period": "MONTHLY",
      "entity_type": "ADDON",
      "entity_id": "addon_seats_10"
    }
  ]
}

Plans

Base plans that add-ons extend

Prices

Configure pricing for add-ons

Subscriptions

How add-ons are attached to subscriptions

Entitlements

Feature access granted by add-ons