Copy page

Business models

API Platform / Pay-Per-Call

The pure usage-based pattern: there is no recurring fee, customers pay only for what they consume, and the unit of consumption is something countable (API calls, tokens, messages, minutes, GB). The hard parts are not the pricing curve - they are ingest at scale, deduplication, real-time visibility, and reconciling what the customer thinks they used against what you billed them.

Real-world examples. OpenAI (per-token, varies by model), Twilio (per-message, per-minute, per-recipient-country), Stripe API (per-call quotas, per-charge fees), Anthropic API (per-token), Mapbox (per-tile-load), SendGrid (per-email). Common shape: a published rate card with graduated discounts above thresholds, real-time usage dashboards in the customer portal, monthly invoice for the prior month's aggregated consumption.

The shape of the problem

The deceptive simplicity of "$X per call" hides:

• Event-rate scale. A real API platform receives millions of events per minute. The metering pipeline can't be the bottleneck - and it can't drop events under load, because dropped events become uncollected revenue.
• Idempotency at the edge. Network retries, client-side bugs, and outages all produce duplicate event submissions. Without deduplication, customers get billed for events you can prove they didn't actually originate.
• Real-time vs period totals. Customers expect to see a usage number in their dashboard within seconds of making a call - while the invoice number for the period only finalizes at month end. The same underlying data has to feed both views.
• Tier crossings during a period. Graduated discounts mean the per-unit rate changes mid-period as the customer crosses thresholds. The invoice has to walk the tiers and bill the cheaper tail correctly.
• Multi-dimensional metering. "Per call" is rarely just per call - it's per-call × per-region or per-token × per-model. The metering must split the same event stream multiple ways.

Kontier blueprint

Concern	Kontier primitive
High-volume event ingest	POST /v1/usage-events (single event or a batch of up to 1,000) with a required idempotency_key
Tier-walking pricing	STAIRCASE pricing model on the product
Real-time customer visibility	GET /v1/usage-events/aggregate (filter by customer_id, subscription_id, product_id, metric_key)
Per-region or per-model breakdown	Meter filter_tree / dimensions on event metadata
Per-model rates	Keyed product: one price per price_key, events carry the key
Usage nothing bills	GET /v1/subscriptions/usage-without-line lists usage the deal has no line for

Build it

IDs in the examples are placeholders: use the id each create call returns.

1. Define the metered product

Code
curl -X POST https://api.kontier.eu/v1/products \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Calls",
    "unit_label": "call",
    "quantity_source": "METERED",
    "pricing_model": "STAIRCASE",
    "tax_category": "DEFAULT"
  }'

2. Define the meter and bind it to the product

Metering is a two-call flow: first create a meter that defines how raw events are aggregated, then bind it to the product as the billable quantity.

Code
# 2a. Create the meter
curl -X POST https://api.kontier.eu/v1/meters \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "api_calls",
    "name": "API Calls",
    "metric_key": "api_calls",
    "function": "SUM",
    "value_field": "quantity",
    "unit_label": "calls"
  }'

Code
# 2b. Bind the meter to the product (meter_id from 2a)
curl -X POST https://api.kontier.eu/v1/products/1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed/meter-bindings \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "meter_id": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
    "pricing_var_name": "api_calls",
    "role": "BILLABLE_QUANTITY"
  }'

function is the aggregation (SUM, COUNT, MAX, MIN, AVG, UNIQUE_COUNT, LAST, P95). value_field names the event field aggregated (required for SUM/MAX/MIN/AVG/P95/LAST, forbidden for COUNT/UNIQUE_COUNT). Deduplication uses each event's idempotency_key by default; set dedup_key_path only if another event field should be the dedup key. Omit window to aggregate over the whole billing period. See Meters.

3. Publish the graduated rate card

Code
curl -X POST https://api.kontier.eu/v1/prices \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "currency":   "USD",
    "list_price": "0",
    "tiers": [
      { "up_to": "10000",   "unit_amount": "0.10" },
      { "up_to": "100000",  "unit_amount": "0.05" },
      { "up_to": "1000000", "unit_amount": "0.03" },
      {                     "unit_amount": "0.01" }
    ]
  }'

Tier up_to and unit_amount are decimal strings; the last tier omits up_to and runs to infinity. With STAIRCASE, each tier rate applies only to the units inside its band. A customer making 250,000 calls pays: 10k × $0.10 + 90k × $0.05 + 150k × $0.03 = $10,000.

The price, the meter binding and the product itself sit in the product's working draft until you publish it:

Code
curl -X POST https://api.kontier.eu/v1/changes \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "operation":    "catalog.publish_version",
    "subject_kind": "product",
    "subject_id":   "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "when":         "now",
    "payload":      { "release_name": "2026 rate card" }
  }'

4. Give the customer a subscription with a metered line

Usage is billed only through a metered line on the customer's subscription. Create the subscription, author revision 1 with one open-ended phase carrying the product, and start it:

Code
curl -X POST https://api.kontier.eu/v1/subscriptions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e", "name": "ApiCo - pay as you go", "currency": "USD" }'

curl -X PUT https://api.kontier.eu/v1/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6/revisions/draft \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "phases": [
      {
        "starts": { "kind": "fixed", "at": "2026-11-01T00:00:00Z" },
        "ends":   { "kind": "never" },
        "then":   "open",
        "reason": "Pay as you go",
        "lines": [
          {
            "product_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
            "origin": { "kind": "product", "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "version": 1 }
          }
        ]
      }
    ]
  }'

curl -X POST https://api.kontier.eu/v1/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6/activate \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

origin.kind: "product" sells the product directly, without a plan; version is the product version you published (1 for the first publish).

5. Ingest events at runtime

Code
curl -X POST https://api.kontier.eu/v1/usage-events \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id":     "0f8fad5b-d9cb-469f-a165-70867728950e",
    "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "product_id":      "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "metric_key":      "api_calls",
    "quantity":        "1",
    "timestamp":       "2026-11-15T14:30:00.123Z",
    "idempotency_key": "req_8b1d7c20-4d6c-4d04-9f78-2a3a06d7b2fc",
    "metadata": {
      "endpoint": "/v1/completions",
      "region":   "us-east-1",
      "model":    "gpt-4"
    }
  }'

Critical fields:

• idempotency_key is required in the body and should be your internal request ID. Submitting the same key twice records the event once. (The Idempotency-Key header protects the HTTP request; the body field dedupes the event.)
• quantity is a non-negative decimal string.
• timestamp should be when the API call actually occurred, not when the event was forwarded; omit it and the event is stamped on arrival.
• metadata keys can drive meter filter_tree / dimensions and analytics breakdowns later.

At volume, send a batch instead: the same endpoint accepts { "events": [ … ] } with 1 to 1,000 events per call.

6. Show the customer their real-time usage

Read totals from GET /v1/usage-events/aggregate. The filters (customer_id, product_id, subscription_id, metric_key) are query params. since (RFC3339) is required; bucket is hour, day (the default) or week; until defaults to now; metric defaults to count (pass sum_quantity to sum the event quantity field).

Code
curl "https://api.kontier.eu/v1/usage-events/aggregate?\
bucket=day&\
metric=sum_quantity&\
customer_id=0f8fad5b-d9cb-469f-a165-70867728950e&\
subscription_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&\
product_id=1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed&\
since=2026-11-01T00:00:00Z&\
until=2026-11-30T23:59:59Z" \
  -H "Authorization: Bearer sk_test_…"

Response (one row per bucket):

Code
{
  "data": {
    "bucket": "day",
    "since": "2026-11-01T00:00:00Z",
    "until": "2026-11-30T23:59:59Z",
    "metric": "sum_quantity",
    "group_by": "none",
    "series": ["total"],
    "rows": [
      {
        "bucket": "2026-11-15T00:00:00Z",
        "sum_totals": { "total": "247534" }
      }
    ]
  }
}

Decimal sum_quantity totals come back as strings (in sum_totals) so they round-trip without float loss; with the default count metric the buckets carry totals instead. For the raw event list (cursor-paginated) call GET /v1/usage-events with the same filters.

Variations

• Multi-dimensional pricing (per-call × per-model). Make the product keyed: link it to a key set with one key per model (gpt-4, gpt-4-turbo, gpt-3.5) and add one price per price_key. Events carry price_key: "gpt-4". The subscription needs one line per key it sells (a keyed product's line must name a price_key); usage under a key the deal has no line for is accepted but billed by nothing, and shows up in GET /v1/subscriptions/usage-without-line.
• Free tier with overage. Set the first STAIRCASE tier to "unit_amount": "0". The customer sees usage but is only billed above the free threshold.
• Per-region pricing. Add a country_code on the price for geo-targeted rates, or use a meter filter_tree / dimensions on metadata.region to split a single event stream.
• Spending caps. Add a thresholds entry to the meter ({ "name": "90% of cap", "comparator": "gte", "value": "900000" }) and subscribe to the meter.threshold_breached webhook; throttle or notify on your side.
• Prepaid usage. Fund a wallet and reserve against it before serving the call with POST /v1/reservations; ingest the event with the hold's hold_id to capture it.

What you don't have to build

• High-throughput event ingest (single events or batches of up to 1,000 on POST /v1/usage-events)
• Idempotency / deduplication on retried submissions (each event's idempotency_key)
• Real-time aggregation between events and the dashboard query
• Tier-walking math for graduated pricing (STAIRCASE tiers handle it deterministically)
• Per-region or per-model fan-out (meter filter_tree / dimensions or keyed products)
• Reconciliation between dashboard usage and invoice quantity (same events on both sides)

Next steps

• Usage Metering - events, batches, deduplication
• Meters - aggregation functions, windows, filters
• Pricing Models - STAIRCASE walks vs VOLUME vs PACKAGE
• Key Sets - one product, many priced dimensions
• Analytics - per-customer, per-product usage trends