Concepts

Pricing Models

Copy page

Pricing models define how charges are calculated within a rate card. Each model suits different business scenarios, from simple flat fees to complex usage-based pricing.

Flat Fee Pricing

Flat fee pricing charges a fixed amount regardless of usage. Use flat_fee rate cards for subscriptions, setup fees, or access charges.

Recurring Subscription

A monthly platform fee that recurs each billing period:

Code
{
  "type": "flat_fee",
  "key": "platform_fee",
  "name": "Platform Fee",
  "billingCadence": "P1M",
  "price": {
    "type": "flat",
    "amount": "99.00"
  }
}

One-Time Setup Fee

A setup fee charged once when the subscription starts (no billingCadence):

Code
{
  "type": "flat_fee",
  "key": "setup_fee",
  "name": "Setup Fee",
  "price": {
    "type": "flat",
    "amount": "500.00"
  }
}

Per-Unit Pricing

Per-unit pricing charges a fixed amount for each unit of metered usage. Use usage_based rate cards linked to a feature.

Code
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "unit",
    "amount": "0.001"
  },
  "entitlementTemplate": {
    "type": "metered",
    "isSoftLimit": true
  }
}

Example: At $0.001 per unit, a customer using 100,000 API calls pays:

100,000 × $0.001 = $100

Tiered Pricing

Tiered pricing varies the price based on usage volume. There are two modes:

Graduated Pricing

Each unit is charged according to the tier it falls into:

Code
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "tiered",
    "mode": "graduated",
    "tiers": [
      { "upToAmount": 1000, "unitPrice": { "amount": "0.10" } },
      { "upToAmount": 10000, "unitPrice": { "amount": "0.05" } },
      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
    ]
  },
  "entitlementTemplate": {
    "type": "metered",
    "isSoftLimit": true
  }
}

Tier	Units	Unit Price
1	0 - 1,000	$0.10
2	1,001 - 10,000	$0.05
3	10,001+	$0.01

Example: A customer using 15,000 units pays:

(1,000 × $0.10) + (9,000 × $0.05) + (5,000 × $0.01) = $100 + $450 + $50 = $600

Volume Pricing

All units are charged at the rate of the highest tier reached:

Code
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "tiered",
    "mode": "volume",
    "tiers": [
      { "upToAmount": 1000, "unitPrice": { "amount": "0.10" } },
      { "upToAmount": 10000, "unitPrice": { "amount": "0.05" } },
      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
    ]
  },
  "entitlementTemplate": {
    "type": "metered",
    "isSoftLimit": true
  }
}

Example: A customer using 15,000 units pays:

15,000 × $0.01 = $150

All units are charged at the tier 3 rate because usage exceeded 10,000.

Included Usage with Overage

Combine a flat fee for included usage with per-unit overage charges. This is a common pattern for "X calls included, then $Y per additional call":

Code
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "tiered",
    "mode": "graduated",
    "tiers": [
      { "upToAmount": 10000, "flatPrice": { "amount": "0" } },
      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
    ]
  },
  "entitlementTemplate": {
    "type": "metered",
    "issueAfterReset": 10000,
    "isSoftLimit": true
  }
}

This grants 10,000 API calls included (via issueAfterReset), then charges $0.01 per additional call.

Package Pricing

Package pricing sells usage in fixed bundles rather than individual units:

Code
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "package",
    "amount": "10.00",
    "quantityPerPackage": 1000
  },
  "entitlementTemplate": {
    "type": "metered",
    "isSoftLimit": true
  }
}

Usage	Packages	Total
0	0	$0
500	1	$10
1,000	1	$10
1,001	2	$20
5,500	6	$60

Usage is rounded up to the next package.

Choosing a Pricing Model

Model	Best For
Flat	Subscriptions, setup fees, fixed-price features
Per-Unit	Simple usage billing where each unit has equal value
Graduated	Volume discounts while maintaining revenue on lower tiers
Volume	Aggressive volume discounts to incentivize high usage
Package	Simplified billing, encouraging bulk purchases

Complete Example

See Plan Examples for step-by-step examples showing how to build plans with different pricing models.