Stripe Billing Meter resource — usage-based billing schema.
See guides/metering.md (landed in Plan 20-06) for the full usage story,
including the two-layer idempotency contract, the 35-day backdating window,
and the v1.billing.meter.error_report_triggered webhook.
Lifecycle
Meters are created once per usage concept, reported against via
LatticeStripe.Billing.MeterEvent.create/3, and eventually retired via
deactivate/3. A deactivated meter can be brought back with reactivate/3;
deletion is not exposed by the Stripe API.
Usage
client = LatticeStripe.Client.new!(api_key: "sk_live_...", finch: MyApp.Finch)
# Create a meter with sum aggregation
{:ok, meter} = LatticeStripe.Billing.Meter.create(client, %{
"display_name" => "API Calls",
"event_name" => "api_call",
"default_aggregation" => %{"formula" => "sum"},
"value_settings" => %{"event_payload_key" => "value"}
})
# Deactivate when no longer needed
{:ok, _meter} = LatticeStripe.Billing.Meter.deactivate(client, meter.id)Summary
Functions
Create a billing meter.
Bang variant of create/3. Raises LatticeStripe.Error on failure.
Deactivate a meter — POST /v1/billing/meters/{id}/deactivate.
Bang variant of deactivate/3. Raises LatticeStripe.Error on failure.
Decode a Stripe-shaped string-keyed map into a %Meter{}.
List billing meters. Supports cursor-based pagination via starting_after
and ending_before, and filtering via status ("active" | "inactive").
Bang variant of list/3. Raises LatticeStripe.Error on failure.
Reactivate a previously-deactivated meter — POST /v1/billing/meters/{id}/reactivate.
Bang variant of reactivate/3. Raises LatticeStripe.Error on failure.
Retrieve a billing meter by ID.
Bang variant of retrieve/3. Raises LatticeStripe.Error on failure.
Returns a lazy stream of all billing meters (auto-pagination).
Update a billing meter.
Bang variant of update/4. Raises LatticeStripe.Error on failure.
Types
@type t() :: %LatticeStripe.Billing.Meter{ created: integer() | nil, customer_mapping: LatticeStripe.Billing.Meter.CustomerMapping.t() | nil, default_aggregation: LatticeStripe.Billing.Meter.DefaultAggregation.t() | nil, display_name: String.t() | nil, event_name: String.t() | nil, extra: map(), id: String.t() | nil, livemode: boolean() | nil, object: String.t() | nil, status: atom() | String.t() | nil, status_transitions: LatticeStripe.Billing.Meter.StatusTransitions.t() | nil, updated: integer() | nil, value_settings: LatticeStripe.Billing.Meter.ValueSettings.t() | nil }
Functions
@spec create(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Create a billing meter.
Requires display_name, event_name, and default_aggregation params
(string keys — Stripe wire format). After param validation, a pre-flight
guard raises ArgumentError on present-but-malformed value_settings for
sum/last formulas (T-20-01 silent-zero trap).
@spec create!(LatticeStripe.Client.t(), map(), keyword()) :: t()
Bang variant of create/3. Raises LatticeStripe.Error on failure.
@spec deactivate(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Deactivate a meter — POST /v1/billing/meters/{id}/deactivate.
Use this instead of update/4 with a status param (Stripe does not
accept that shape). Deactivated meters reject new events with the
archived_meter error code.
@spec deactivate!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Bang variant of deactivate/3. Raises LatticeStripe.Error on failure.
Decode a Stripe-shaped string-keyed map into a %Meter{}.
Nested sub-objects (default_aggregation, customer_mapping,
value_settings, status_transitions) are decoded via their respective
from_map/1 callbacks. Unknown top-level keys land in :extra.
@spec list(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
List billing meters. Supports cursor-based pagination via starting_after
and ending_before, and filtering via status ("active" | "inactive").
@spec list!(LatticeStripe.Client.t(), map(), keyword()) :: LatticeStripe.Response.t()
Bang variant of list/3. Raises LatticeStripe.Error on failure.
@spec reactivate(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Reactivate a previously-deactivated meter — POST /v1/billing/meters/{id}/reactivate.
@spec reactivate!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Bang variant of reactivate/3. Raises LatticeStripe.Error on failure.
@spec retrieve(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieve a billing meter by ID.
@spec retrieve!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Bang variant of retrieve/3. Raises LatticeStripe.Error on failure.
@spec stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all billing meters (auto-pagination).
Emits individual %Meter{} structs, fetching additional pages as needed.
Raises LatticeStripe.Error if any page fetch fails.
@spec update(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Update a billing meter.
At time of writing, Stripe only mutates display_name; other keys in
params are passed through to the API for forward compatibility. If Stripe
later exposes additional mutable fields, this function will begin accepting
them automatically without a library change.
@spec update!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Bang variant of update/4. Raises LatticeStripe.Error on failure.