LatticeStripe.Event (LatticeStripe v0.2.0)

Operations on Stripe Event objects.

Events represent actions that occurred in your Stripe account — payment succeeded, customer created, subscription cancelled, etc. Events are read-only (you cannot create or modify them via the API). LatticeStripe delivers webhook events as typed %Event{} structs via LatticeStripe.Webhook.construct_event/3.

Usage

client = LatticeStripe.Client.new!(api_key: "sk_live_...", finch: MyApp.Finch)

# Retrieve a specific event
{:ok, event} = LatticeStripe.Event.retrieve(client, "evt_1NxGkW2eZvKYlo2CvN93zMW1")

# List recent events
{:ok, resp} = LatticeStripe.Event.list(client, %{"limit" => "10", "type" => "payment_intent.succeeded"})
events = resp.data.data  # [%Event{}, ...]

# Stream all events lazily (auto-pagination)
client
|> LatticeStripe.Event.stream!(%{"type" => "customer.created"})
|> Stream.take(100)
|> Enum.each(&handle_event/1)

Inspect

The Inspect implementation hides data, request, account, and extra fields to keep inspect output concise. Only id, type, object, created, and livemode are shown.

Stripe API Reference

See the Stripe Events API for the full object reference, and the event types catalog for all available event type strings.

Summary

Types

t()

A Stripe Event object.

Functions

from_map(map)

Converts a decoded Stripe API map to a %Event{} struct.

list(client, params \\ %{}, opts \\ [])

Lists Events with optional filters.

list!(client, params \\ %{}, opts \\ [])

Like list/3 but raises LatticeStripe.Error on failure.

retrieve(client, id, opts \\ [])

Retrieves an Event by ID.

retrieve!(client, id, opts \\ [])

Like retrieve/3 but raises LatticeStripe.Error on failure.

stream!(client, params \\ %{}, opts \\ [])

Returns a lazy stream of all Events matching the given params (auto-pagination).

Types

t()

@type t() :: %LatticeStripe.Event{
  account: String.t() | nil,
  api_version: String.t() | nil,
  context: String.t() | nil,
  created: integer() | nil,
  data: map() | nil,
  extra: map(),
  id: String.t() | nil,
  livemode: boolean() | nil,
  object: String.t(),
  pending_webhooks: integer() | nil,
  request: map() | nil,
  type: String.t() | nil
}

A Stripe Event object.

Events represent actions in your Stripe account. Delivered as webhook payloads or retrieved via the Events API. The data.object map contains the full Stripe object snapshot at the time of the event — its shape varies by type.

See the Stripe Events API for field definitions and the event catalog for all event types.

id - Event ID (e.g., "evt_1NxGkW2eZvKYlo2CvN93zMW1")
type - Event type string (e.g., "payment_intent.succeeded", "customer.created")
data - Raw map with "object" key containing the Stripe object snapshot
created - Unix timestamp when the event was created
livemode - true for live mode, false for test mode
api_version - Stripe API version the event was rendered with
pending_webhooks - Number of webhook endpoints yet to receive this event
request - Original request that triggered the event (raw map), or nil
account - Connected account ID for Connect events, or nil
extra - Any unknown fields from the Stripe response

Functions

from_map(map)

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

Converts a decoded Stripe API map to a %Event{} struct.

Maps all known Stripe Event fields. Any unrecognized fields are collected into the extra map so no data is silently lost. Always succeeds (infallible).

The data and request fields are kept as raw maps — no further typing is applied since event data varies by event type.

Example

event = LatticeStripe.Event.from_map(%{
  "id" => "evt_1NxGkW2eZvKYlo2CvN93zMW1",
  "type" => "payment_intent.succeeded",
  "object" => "event",
  "data" => %{"object" => %{"id" => "pi_abc123"}}
})

list(client, params \\ %{}, opts \\ [])

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

Lists Events with optional filters.

Sends GET /v1/events and returns {:ok, %Response{data: %List{}}} with typed %Event{} items.

Parameters

client - A %LatticeStripe.Client{} struct
params - Filter params (e.g., %{"limit" => "10", "type" => "payment_intent.succeeded"})
opts - Per-request overrides

Returns

{:ok, %Response{data: %List{data: [%Event{}, ...]}}} on success
{:error, %LatticeStripe.Error{}} on failure

list!(client, params \\ %{}, opts \\ [])

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

Like list/3 but raises LatticeStripe.Error on failure.

retrieve(client, id, opts \\ [])

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

Retrieves an Event by ID.

Sends GET /v1/events/:id and returns {:ok, %Event{}}.

Parameters

client - A %LatticeStripe.Client{} struct
id - The event ID string (e.g., "evt_1NxGkW2eZvKYlo2CvN93zMW1")
opts - Per-request overrides

Returns

{:ok, %Event{}} on success
{:error, %LatticeStripe.Error{}} on failure

retrieve!(client, id, opts \\ [])

@spec retrieve!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()

Like retrieve/3 but raises LatticeStripe.Error on failure.

stream!(client, params \\ %{}, opts \\ [])

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

Returns a lazy stream of all Events matching the given params (auto-pagination).

Emits individual %Event{} structs, fetching additional pages as needed. Raises LatticeStripe.Error if any page fetch fails.

Parameters

client - A %LatticeStripe.Client{} struct
params - Filter params (e.g., %{"type" => "customer.created", "limit" => "100"})
opts - Per-request overrides

Returns

An Enumerable.t() of %Event{} structs.