Operations on Stripe Customer objects.
A Customer in Stripe represents a person or company you charge money from or send money to. Customers let you save payment methods, track charges, and associate subscriptions.
Usage
client = LatticeStripe.Client.new!(api_key: "sk_live_...", finch: MyApp.Finch)
# Create a customer
{:ok, customer} = LatticeStripe.Customer.create(client, %{
"email" => "user@example.com",
"name" => "Jane Doe",
"metadata" => %{"user_id" => "usr_123"}
})
# Retrieve a customer
{:ok, customer} = LatticeStripe.Customer.retrieve(client, customer.id)
# List customers with filters
{:ok, resp} = LatticeStripe.Customer.list(client, %{"limit" => "10"})
customers = resp.data.data # [%Customer{}, ...]
# Search customers
{:ok, resp} = LatticeStripe.Customer.search(client, "email:'user@example.com'")
# Stream all customers lazily (auto-pagination)
client
|> LatticeStripe.Customer.stream!()
|> Stream.take(100)
|> Enum.each(&process_customer/1)PII and Inspect
The Inspect implementation hides personally-identifiable information
(email, name, phone, description, address, shipping). Only id, object,
livemode, and deleted are shown in inspect output.
Stripe API Reference
See the Stripe Customer API for the full object reference and available parameters.
Summary
Functions
Creates a new Customer.
Like create/3 but raises LatticeStripe.Error on failure.
Deletes a Customer by ID.
Like delete/3 but raises LatticeStripe.Error on failure.
Converts a decoded Stripe API map to a %Customer{} struct.
Lists Customers with optional filters.
Like list/3 but raises LatticeStripe.Error on failure.
Retrieves a Customer by ID.
Like retrieve/3 but raises LatticeStripe.Error on failure.
Searches Customers using Stripe's search query language.
Like search/3 but raises LatticeStripe.Error on failure.
Returns a lazy stream of all Customers matching the search query (auto-pagination).
Returns a lazy stream of all Customers matching the given params (auto-pagination).
Updates a Customer by ID.
Like update/4 but raises LatticeStripe.Error on failure.
Types
@type t() :: %LatticeStripe.Customer{ address: map() | nil, balance: integer() | nil, business_name: String.t() | nil, cash_balance: map() | nil, created: integer() | nil, currency: String.t() | nil, customer_account: map() | nil, default_source: String.t() | nil, deleted: boolean(), delinquent: boolean() | nil, description: String.t() | nil, discount: map() | nil, email: String.t() | nil, extra: map(), id: String.t() | nil, individual_name: String.t() | nil, invoice_credit_balance: map() | nil, invoice_prefix: String.t() | nil, invoice_settings: map() | nil, livemode: boolean() | nil, metadata: map() | nil, name: String.t() | nil, next_invoice_sequence: integer() | nil, object: String.t(), phone: String.t() | nil, preferred_locales: [String.t()] | nil, shipping: map() | nil, sources: map() | nil, subscriptions: map() | nil }
A Stripe Customer object.
See the Stripe Customer API for field definitions.
Functions
@spec create(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Creates a new Customer.
Sends POST /v1/customers with the given params and returns {:ok, %Customer{}}.
Parameters
client- A%LatticeStripe.Client{}structparams- Map of customer attributes (e.g.,%{"email" => "...", "name" => "..."})opts- Per-request overrides (e.g.,[idempotency_key: "..."])
Returns
{:ok, %Customer{}}on success{:error, %LatticeStripe.Error{}}on failure
Example
{:ok, customer} = LatticeStripe.Customer.create(client, %{
"email" => "user@example.com",
"name" => "Jane Doe"
})
# Error handling
case LatticeStripe.Customer.create(client, %{"email" => "user@example.com"}) do
{:ok, customer} -> customer.id
{:error, %LatticeStripe.Error{type: :invalid_request_error} = err} -> handle_error(err)
{:error, %LatticeStripe.Error{}} = err -> handle_error(err)
end@spec create!(LatticeStripe.Client.t(), map(), keyword()) :: t()
Like create/3 but raises LatticeStripe.Error on failure.
@spec delete(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Deletes a Customer by ID.
Sends DELETE /v1/customers/:id and returns {:ok, %Customer{deleted: true}}.
Parameters
client- A%LatticeStripe.Client{}structid- The customer ID stringopts- Per-request overrides
Returns
{:ok, %Customer{deleted: true}}on success{:error, %LatticeStripe.Error{}}on failure
@spec delete!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Like delete/3 but raises LatticeStripe.Error on failure.
Converts a decoded Stripe API map to a %Customer{} struct.
Maps all known Stripe Customer fields. Any unrecognized fields are collected
into the extra map so no data is silently lost.
Example
customer = LatticeStripe.Customer.from_map(%{
"id" => "cus_123",
"email" => "user@example.com",
"object" => "customer"
})@spec list(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Lists Customers with optional filters.
Sends GET /v1/customers and returns {:ok, %Response{data: %List{}}} with
typed %Customer{} items.
Parameters
client- A%LatticeStripe.Client{}structparams- Filter params (e.g.,%{"limit" => "10", "email" => "user@example.com"})opts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%Customer{}, ...]}}}on success{:error, %LatticeStripe.Error{}}on failure
Example
{:ok, resp} = LatticeStripe.Customer.list(client, %{"limit" => "20"})
Enum.each(resp.data.data, &IO.inspect/1)@spec list!(LatticeStripe.Client.t(), map(), keyword()) :: LatticeStripe.Response.t()
Like list/3 but raises LatticeStripe.Error on failure.
@spec retrieve(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieves a Customer by ID.
Sends GET /v1/customers/:id and returns {:ok, %Customer{}}.
Parameters
client- A%LatticeStripe.Client{}structid- The customer ID string (e.g.,"cus_123")opts- Per-request overrides
Returns
{:ok, %Customer{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec retrieve!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Like retrieve/3 but raises LatticeStripe.Error on failure.
@spec search(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Searches Customers using Stripe's search query language.
Sends GET /v1/customers/search with the query string and returns typed results.
Note: search results have eventual consistency — newly created customers may not
appear immediately.
Parameters
client- A%LatticeStripe.Client{}structquery- Stripe search query string (e.g.,"email:'user@example.com'")opts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%Customer{}, ...]}}}on success{:error, %LatticeStripe.Error{}}on failure
Example
{:ok, resp} = LatticeStripe.Customer.search(client, "email:'billing@company.com'")@spec search!(LatticeStripe.Client.t(), String.t(), keyword()) :: LatticeStripe.Response.t()
Like search/3 but raises LatticeStripe.Error on failure.
@spec search_stream!(LatticeStripe.Client.t(), String.t(), keyword()) :: Enumerable.t()
Returns a lazy stream of all Customers matching the search query (auto-pagination).
Emits individual %Customer{} structs, fetching additional search pages as needed.
Raises LatticeStripe.Error if any page fetch fails.
Parameters
client- A%LatticeStripe.Client{}structquery- Stripe search query stringopts- Per-request overrides
Returns
An Enumerable.t() of %Customer{} structs.
@spec stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all Customers matching the given params (auto-pagination).
Emits individual %Customer{} structs, fetching additional pages as needed.
Raises LatticeStripe.Error if any page fetch fails.
Parameters
client- A%LatticeStripe.Client{}structparams- Filter params (e.g.,%{"limit" => "100"})opts- Per-request overrides
Returns
An Enumerable.t() of %Customer{} structs.
Example
client
|> LatticeStripe.Customer.stream!()
|> Stream.take(500)
|> Enum.to_list()@spec update(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Updates a Customer by ID.
Sends POST /v1/customers/:id with the given params and returns {:ok, %Customer{}}.
Parameters
client- A%LatticeStripe.Client{}structid- The customer ID stringparams- Map of fields to updateopts- Per-request overrides
Returns
{:ok, %Customer{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec update!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like update/4 but raises LatticeStripe.Error on failure.