Copy page

Concepts

Pricing Models

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 subscription fee that recurs each billing period and is collected in advance:

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

Each billing period — every month for P1M — Zuplo adds a $99.00 line item for this rate card to the customer's Stripe Invoice. Because paymentTerm is in_advance (the default for flat prices), the customer is charged at the start of the period rather than the end.

The rate card's billingCadence must align with the plan's billingCadence — see Rate Cards → Billing Cadence for the alignment rule. A flat-fee rate card like this one doesn't need a featureKey (see Rate Cards Without Features) — the rate card's key and name appear directly on the customer's invoice.

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_requests",
  "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_requests",
  "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_requests",
  "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_requests",
  "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_requests",
  "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.