Rate Plans

Rate Plans (also called Rate Cards) define how much you charge for each billable unit. A single rate plan can price multiple products and multiple billable units, each with its own pricing model, tiers, limits, and rollover settings.

Pricing Models

Aforo supports six pricing models:

Per Unit

The simplest model. Charge a fixed price per unit consumed, after subtracting any included free quota.

charge = max(0, quantity - includedFree) × ratePerUnit

Best for: API call charging, token metering, event counting.

Flat Rate

A fixed charge regardless of usage. Typically used as a base fee on top of usage charges.

charge = flatRate

Best for: Platform access fees, monthly minimums.

Percentage

Charge a fraction of the underlying transaction value, with an optional minimum floor.

charge = max(minFee, rawValue × ratePercent / 100)

Best for: Payment processing, revenue share, commission models.

Included Quota

Free up to a quota, then charge for overages. Supports both per-unit and block pricing for overages.

Per-unit overage:

charge = max(0, quantity - includedFree) × overageRate

Block overage (when blockSize is set):

charge = ceil(max(0, quantity - includedFree) / blockSize) × overageRate

Best for: Freemium tiers, API plans with monthly credits.

Graduated (Staircase)

Each tier is priced independently. Units in tier 1 are charged at tier 1's rate, units in tier 2 at tier 2's rate, etc.

For 15,000 units: (1,000 × $0.010) + (9,000 × $0.008) + (5,000 × $0.005) = $10 + $72 + $25 = $107

Best for: Volume-sensitive pricing where large consumers should pay a blended rate.

Volume Tiered

The entire volume is charged at the rate of the tier where the total falls.

For 15,000 units (falls in tier 3): 15,000 × $0.005 = $75

Best for: Simple quantity discounts, wholesale pricing.

Configuring a Rate Plan

Multi-Product, Multi-Metric

A single rate plan links to:

• Multiple products — one rate plan can cover an entire product family
• Multiple billable units — each with its own independent pricing model and tier structure

{
  "name": "Growth Plan — Q2 2026",
  "productIds": ["prod_api_v2", "prod_agentic_v1"],
  "metricConfigs": [
    {
      "metricId": "metric_api_calls",
      "pricingModel": "GRADUATED",
      "tiers": [
        { "tierStart": 0, "tierEnd": 1000, "unitPrice": 0.010 },
        { "tierStart": 1001, "unitPrice": 0.005 }
      ]
    },
    {
      "metricId": "metric_input_tokens",
      "pricingModel": "PER_UNIT",
      "rate": 0.000002,
      "includedFree": 100000
    }
  ]
}

Limits and Guardrails

Each metric config can have limits that enforce usage thresholds:

Included Quota & Rollover

Set includedFree to give customers a monthly free allowance. Enable rollover: true to let unused quota carry forward to the next billing period, up to rolloverMax units.

Version Pinning

When you update pricing on a rate plan that has active subscriptions, Aforo automatically creates a new rate plan version. Existing subscribers are pinned to the version they signed up with — they will not see price changes until explicitly migrated.

This gives you safe price updates without surprise bills for existing customers.

Billing Timing

Per metric config, set billingTiming:

• ARREARS — Charge at end of billing period (postpaid, default)
• ADVANCE — Charge at start of period (prepaid credit burn)