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 eight 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 (Revenue Share)

Best when you take a cut of money that flows through your product — payments, marketplaces, commissions. You charge a percentage of a transaction amount, with an optional minimum floor.

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

The ratePercent is a percent, not a multiplier: 2.9 means 2.9%, and it's validated to be between 0 and 100. A single order of $500 at 2.9% bills $14.50.

How the amount reaches Aforo. Revenue Share prices a monetary quantity, so you send the transaction amount as the event quantity, and the metric aggregates it with SUM over the billing period — the period total is your GMV. Your monthly charge is ratePercent% of that GMV.

# Each transaction reports its dollar value as quantity:
curl -X POST https://ingest.aforo.ai/v1/ingest \
  -H "Authorization: Bearer $AFORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"cus_123","metricName":"transaction_value","quantity":500.00,"timestamp":"2026-07-01T10:00:00Z"}'
# Period GMV = SUM of all quantities. 2.9% of a $250,000 month = $7,250.

Best for: Payment processing, revenue share, marketplace commissions.

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

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.

Staircase

A flat package price for whichever tier the total lands in — you pay the tier's fixed amount outright, not a per-unit rate. (Contrast with Volume Tiered, which multiplies the whole volume by the tier's unit rate.)

Best for: Packaged plans where each tier is a named bundle — "up to 10k calls = $99, up to 100k = $499".

Outcome-Based

Charge by the outcome of the work, not the raw count. Each event carries an execution outcome (e.g. SUCCESS, ERROR, TIMEOUT, PARTIAL) and you assign a weight (0.0–1.0) per outcome, so a failed call can bill at a fraction — or nothing.

Best for: AI agents and workflows where you only want to charge for work that actually succeeded.

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
    }
  ]
}

Per-dimension pricing

Beyond the per-metric config, a rate plan can weight individual dimensions of a metric with their own multipliers via its dimensionPricing map — per-tool pricing on an MCP Server, per-endpoint pricing on an Agentic API, or per-capability pricing on an AI Agent. Keys are the dimension names; values are multipliers applied to the metric's base rate:

{
  "pricingModel": "PER_UNIT",
  "dimensionPricing": { "web_search": 1.5, "generate_image": 3.0, "summarize": 0.5 },
  "metricConfigs": [{ "metricName": "Tool Invocations", "model": "PER_UNIT", "rate": 0.01, "includedFree": 0 }]
}

Multipliers only fan out into separate line items on a PER_UNIT metric with no included free tier — on other models the plan bills the aggregate as one line at the base rate. See MCP Server for the per-tool walk-through and the reasoning behind that rule.

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)