# `LatticeStripe.Customer`
[🔗](https://github.com/szTheory/lattice_stripe/blob/v0.2.0/lib/lattice_stripe/customer.ex#L1)

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](https://docs.stripe.com/api/customers) for the full
object reference and available parameters.

# `t`

```elixir
@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](https://docs.stripe.com/api/customers/object) for field definitions.

# `create`

```elixir
@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{}` struct
- `params` - 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

# `create!`

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

Like `create/3` but raises `LatticeStripe.Error` on failure.

# `delete`

```elixir
@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{}` struct
- `id` - The customer ID string
- `opts` - Per-request overrides

## Returns

- `{:ok, %Customer{deleted: true}}` on success
- `{:error, %LatticeStripe.Error{}}` on failure

# `delete!`

```elixir
@spec delete!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
```

Like `delete/3` but raises `LatticeStripe.Error` on failure.

# `from_map`

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

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"
    })

# `list`

```elixir
@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{}` struct
- `params` - 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)

# `list!`

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

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

# `retrieve`

```elixir
@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{}` struct
- `id` - The customer ID string (e.g., `"cus_123"`)
- `opts` - Per-request overrides

## Returns

- `{:ok, %Customer{}}` on success
- `{:error, %LatticeStripe.Error{}}` on failure

# `retrieve!`

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

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

# `search`

```elixir
@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{}` struct
- `query` - 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'")

# `search!`

```elixir
@spec search!(LatticeStripe.Client.t(), String.t(), keyword()) ::
  LatticeStripe.Response.t()
```

Like `search/3` but raises `LatticeStripe.Error` on failure.

# `search_stream!`

```elixir
@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{}` struct
- `query` - Stripe search query string
- `opts` - Per-request overrides

## Returns

An `Enumerable.t()` of `%Customer{}` structs.

# `stream!`

```elixir
@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{}` struct
- `params` - 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()

# `update`

```elixir
@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{}` struct
- `id` - The customer ID string
- `params` - Map of fields to update
- `opts` - Per-request overrides

## Returns

- `{:ok, %Customer{}}` on success
- `{:error, %LatticeStripe.Error{}}` on failure

# `update!`

```elixir
@spec update!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
```

Like `update/4` but raises `LatticeStripe.Error` on failure.

---

*Consult [api-reference.md](api-reference.md) for complete listing*