# Stripe Usage-Based / Metered Billing — Official API Reference

> Local reference distilled from official Stripe documentation for the Pro hybrid
> (committed base + metered overage) billing slice.
>
> **Cited:** 2026-07-07 (Asia/Seoul). API surface: Billing Meters (v1) + Meter Events (v1/v2).
> **Note:** Stripe now surfaces Metronome as its recommended platform for *new* high-volume
> integrations, but the first-party **Billing Meters API documented here is fully supported**
> and is the correct primitive for a self-serve metered-overage subscription. Sources below.

## Sources (official URLs)

| # | Topic | URL |
|---|-------|-----|
| S1 | Usage-based billing overview | https://docs.stripe.com/billing/subscriptions/usage-based |
| S2 | Create a Billing Meter (`POST /v1/billing/meters`) | https://docs.stripe.com/api/billing/meter/create |
| S3 | Create a Meter Event (`POST /v1/billing/meter_events`) | https://docs.stripe.com/api/billing/meter-event/create |
| S4 | Meter Event object v2 (dedup window) (`POST /v2/billing/meter_events`) | https://docs.stripe.com/api/v2/billing/meter-events/object |
| S5 | Create a Price (metered / tiered) (`POST /v1/prices`) | https://docs.stripe.com/api/prices/create |
| S6 | Create a Subscription (multi-item) (`POST /v1/subscriptions`) | https://docs.stripe.com/api/subscriptions/create |
| S7 | Recording usage | https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage |
| S8 | Advanced usage-based (flat fee + overage) | https://docs.stripe.com/billing/subscriptions/usage-based/advanced/compare |

---

## Data model (end to end)

```
Billing Meter  ──defines──▶  event_name + aggregation (sum/count/last)
      ▲                                   │
      │ recurring.meter                   │ meter events (usage) reference event_name
      │                                   ▼
  Metered Price  ──item──▶  Subscription  ◀──item── Licensed base Price (committed fee)
      │                          │
   tiered/per_unit               ▼
                        End of billing period: aggregated usage → invoice line item
```

The **hybrid** = one Subscription carrying **two items**:
1. a **licensed** base price (fixed committed fee, `usage_type` unset/licensed, has `quantity`), and
2. a **metered** price linked to a Meter (`usage_type=metered`, **no `quantity`**), whose graduated
   tiers make the *included allotment* cost 0 and only bill the **overage** per unit.

---

## 1. Create a Billing Meter — `POST /v1/billing/meters` (S2)

A Meter specifies how to aggregate meter events over a billing period.

Key parameters:
- `display_name` (string, required) — internal name, not shown to customers.
- `event_name` (string, required, max 100 chars) — links meter to its events.
- `default_aggregation.formula` (enum, required) — `sum` | `count` | `last`.
- `value_settings.event_payload_key` (string) — payload key holding the numeric value (default `value`).
- `customer_mapping.type` (enum) — `by_id`.
- `customer_mapping.event_payload_key` (string) — payload key holding the customer id (default `stripe_customer_id`).
- `event_time_window` (nullable enum, optional) — `hour` | `day` for pre-aggregated events.

Python signature:
```python
stripe.billing.Meter.create(
    display_name="Pro API Calls",
    event_name="pro_api_call",
    default_aggregation={"formula": "sum"},
    value_settings={"event_payload_key": "value"},
    customer_mapping={"type": "by_id", "event_payload_key": "stripe_customer_id"},
)
# -> billing.meter { id: "mtr_...", status: "active", ... }
```

## 2. Record a Meter Event — `POST /v1/billing/meter_events` (S3, S4)

Reports one usage event. Aggregated into invoice line items at end of period.

Key parameters:
- `event_name` (string, required) — must match a Meter's `event_name`.
- `payload` (object, required) — must contain the meter's `customer_mapping.event_payload_key`
  (default `stripe_customer_id`) and `value_settings.event_payload_key` (default `value`).
- `identifier` (string, optional) — **idempotency / dedup key**. Uniqueness is enforced within a
  **rolling 24-hour window**; a repeated `identifier` is not counted twice. If omitted, Stripe
  generates one. Recommend a globally unique id (UUID / deterministic business key). (S4)
- `timestamp` (unix seconds, optional) — must be **within the past 35 calendar days or up to 5
  minutes in the future**; defaults to now. (S4)

Python signature:
```python
stripe.billing.MeterEvent.create(
    event_name="pro_api_call",
    payload={"stripe_customer_id": "cus_123", "value": "25"},
    identifier="pro_api_call:cus_123:2026-07-07T09:00Z:req_abc",  # dedup within 24h
    timestamp=1751878800,  # optional
)
```
> v2 equivalent `POST /v2/billing/meter_events` returns `v2.billing.meter_event` and does
> synchronous validation; same `identifier` 24h-uniqueness rule. (S4)

## 3a. Create a metered Price — `POST /v1/prices` (S5)

Link a price to the meter and choose per-unit or tiered.

Key parameters:
- `currency` (required) — e.g. `usd`.
- `product` or `product_data` (one required).
- `recurring.interval` (required) — `day` | `week` | `month` | `year`.
- `recurring.usage_type` = `metered` (required for usage billing).
- `recurring.meter` = `<meter id>` (required for metered) — ties price to the Meter from step 1.
- `billing_scheme` — `per_unit` (with `unit_amount`) or `tiered`.
- For tiered overage: `tiers_mode` = `graduated` | `volume`, and `tiers[]` = `{up_to, unit_amount}`.

Graduated overage example (first N units free/included, rest billed):
```python
stripe.Price.create(
    currency="usd",
    product="prod_pro",
    recurring={"interval": "month", "usage_type": "metered", "meter": "mtr_..."},
    billing_scheme="tiered",
    tiers_mode="graduated",
    tiers=[
        {"up_to": 10000, "unit_amount": 0},     # included allotment (covered by base fee)
        {"up_to": "inf", "unit_amount": 2},     # $0.02/unit overage above the allotment
    ],
)
```

## 3b. Create the base (committed) Price — `POST /v1/prices` (S5)

Fixed committed fee = a licensed recurring price (no `usage_type=metered`):
```python
stripe.Price.create(
    currency="usd", product="prod_pro",
    unit_amount=2000,                      # $20.00 committed base
    recurring={"interval": "month"},       # licensed (default usage_type)
)
```

## 4. Create the hybrid Subscription — `POST /v1/subscriptions` (S6)

One subscription, two items. **Metered items must NOT include `quantity`.**
```python
stripe.Subscription.create(
    customer="cus_123",
    items=[
        {"price": "price_base",   "quantity": 1},  # licensed committed fee
        {"price": "price_metered"},                 # metered overage — no quantity
    ],
    idempotency_key="sub-create:cus_123:pro-v1",    # safe retry (request header)
)
```
- Metered usage from the previous period is charged **alongside** the fixed base for the new period
  on a **single invoice** at each renewal. (S6, quantities doc)
- Use the `Idempotency-Key` request header to safely retry create requests (returns the same object).

---

## Overage calculation (concept)

Overage is computed by Stripe, not the app: it aggregates meter events per customer per period via
`default_aggregation.formula`, then applies the metered price's tiers. With `graduated` tiers where
tier-1 (`up_to = included_allotment`) has `unit_amount = 0`, the customer pays only for units above
the allotment:

```
billed_overage = max(0, aggregated_usage - included_allotment) * overage_unit_amount
invoice_total  = committed_base_fee + billed_overage        # single invoice at renewal
```

App-side we only *emit events* and (optionally) *mirror a usage estimate* for UX; the ledger of
record is Stripe's aggregation.

## Idempotency & correctness rules (official)

- **Meter events:** set a deterministic `identifier`; dedup is enforced for a rolling 24h window (S4).
  Choose one identifier per real-world usage unit so retries/at-least-once delivery never double-count.
- **Timestamp:** only accepted within past 35 days / +5 min; late or clock-skewed events are rejected (S4).
- **Write APIs (Meter/Price/Subscription create):** pass the `Idempotency-Key` header to make retries safe (S6).