LatticeStripe.Billing.MeterEvent (LatticeStripe v1.7.13)

Stripe Billing MeterEvent — hot-path usage reporting. Create-only; Stripe exposes no retrieve/list operations for events. See guides/metering.md for the full AccrueLike.UsageReporter recipe and the two-layer idempotency contract.

Summary

Types

t()

Functions

create(client, params, opts \\ [])

Report a metered usage event to Stripe.

create!(client, params, opts \\ [])

Bang variant of create/3. Raises LatticeStripe.Error on failure.

from_map(map)

Decode a Stripe-shaped string-keyed map into a %MeterEvent{}.

Types

t()

@type t() :: %LatticeStripe.Billing.MeterEvent{
  created: integer() | nil,
  event_name: String.t() | nil,
  identifier: String.t() | nil,
  livemode: boolean() | nil,
  payload: map() | nil,
  timestamp: integer() | nil
}

Functions

create(client, params, opts \\ [])

@spec create(LatticeStripe.Client.t(), map(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Report a metered usage event to Stripe.

Params

event_name (required, string) — must match a Billing.Meter.event_name
payload (required, map) — customer-mapping key plus the numeric value (for sum/last meters); the payload key that carries the value is the meter's value_settings.event_payload_key (default "value")
timestamp (optional, integer — Unix seconds) — when the usage occurred; must be within the 35-day backdating window and no more than 5 minutes in the future
identifier (optional, string, ≤100 chars) — body-level (business-layer) idempotency; Stripe dedups on this for 24 hours. Use a stable domain-derived value (e.g. "inv_123:item_456")

Opts

idempotency_key: (optional, string) — transport-layer (HTTP header) idempotency; replays the exact previous response for the same key on network retries. Orthogonal to body identifier. Set BOTH in production for full safety: identifier protects against duplicate domain events, idempotency_key: protects against network-level retries.
stripe_account: (optional, string) — acct_* for Connect scenarios

Return value — IMPORTANT

{:ok, %MeterEvent{}} means Stripe accepted for processing — it does not mean the event has been recorded against a customer. Customer-mapping validation happens asynchronously in Stripe's billing pipeline. The ONLY way to detect customer-mapping failures, invalid values, or a missing payload key is to subscribe to the v1.billing.meter.error_report_triggered webhook. See guides/metering.md → "Reconciliation via webhooks" for the error code table and remediation patterns.

Example

{:ok, event} = LatticeStripe.Billing.MeterEvent.create(client, %{
  "event_name" => "api_call",
  "payload" => %{"stripe_customer_id" => "cus_123", "value" => "1"},
  "identifier" => "req_abc"
}, idempotency_key: "req_abc")

create!(client, params, opts \\ [])

@spec create!(LatticeStripe.Client.t(), map(), keyword()) :: t()

Bang variant of create/3. Raises LatticeStripe.Error on failure.

from_map(map)

@spec from_map(map()) :: t()

Decode a Stripe-shaped string-keyed map into a %MeterEvent{}.

MeterEvent has no nested sub-objects. Unknown keys are silently dropped (no :extra field) per EVENT-05 minimal-struct contract.