# `LatticeStripe.Dispute`
[🔗](https://github.com/szTheory/lattice_stripe/blob/v2.2.2/lib/lattice_stripe/dispute.ex#L1)

Operations on Stripe Dispute objects.

Disputes are created automatically by Stripe when a cardholder or bank
challenges a payment. This module covers the dispute lifecycle after that
point: retrieval, listing, metadata updates, safe evidence staging,
irreversible evidence submission, and irreversible dispute closure.

There is no `create/3` or `delete/3` API because disputes are not developer-
created resources in Stripe.

## Evidence workflow

- `update/4` is the raw power-user entry point for `POST /v1/disputes/:id`
- `update_evidence/4` stages evidence safely and always forces `submit: false`
- `submit_evidence/3` sends `submit: true` with no evidence payload

## Stripe API Reference

See the [Stripe Disputes API](https://docs.stripe.com/api/disputes).

# `t`

```elixir
@type t() :: %LatticeStripe.Dispute{
  amount: integer() | nil,
  balance_transactions: [LatticeStripe.BalanceTransaction.t()] | nil,
  charge: LatticeStripe.Charge.t() | String.t() | nil,
  created: integer() | nil,
  currency: String.t() | nil,
  enhanced_eligibility_types: [String.t()] | nil,
  evidence: LatticeStripe.Dispute.Evidence.t() | nil,
  evidence_details: LatticeStripe.Dispute.EvidenceDetails.t() | nil,
  extra: map(),
  id: String.t() | nil,
  is_charge_refundable: boolean() | nil,
  livemode: boolean() | nil,
  metadata: map() | nil,
  object: String.t(),
  payment_intent: LatticeStripe.PaymentIntent.t() | String.t() | nil,
  payment_method_details: LatticeStripe.Dispute.PaymentMethodDetails.t() | nil,
  reason: atom() | String.t() | nil,
  status: atom() | String.t() | nil
}
```

A Stripe Dispute object.

See the [Stripe Dispute object](https://docs.stripe.com/api/disputes/object)
for field definitions.

# `close`

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

Closes a Dispute by accepting the loss.

Sends `POST /v1/disputes/:id/close` with an empty body.

## Irreversibility

Closing is irreversible. The dispute status changes to `lost` and the
disputed amount plus any dispute fees are permanently deducted from your
Stripe balance. This cannot be undone via the API or Stripe Dashboard.

# `close!`

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

Like `close/3` but raises on failure.

# `from_map`

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

# `list`

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

Lists Disputes with optional filters.

Sends `GET /v1/disputes`.

# `list!`

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

Like `list/3` but raises on failure.

# `retrieve`

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

Retrieves a Dispute by ID.

Sends `GET /v1/disputes/:id`.

# `retrieve!`

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

Like `retrieve/3` but raises on failure.

# `stream!`

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

Returns a lazy stream of Disputes matching the given filters.

# `submit_evidence`

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

Submits previously staged evidence to the issuing bank.

## Irreversibility

Evidence submission locks the response sent to the issuing bank. Once
submitted, you cannot modify the evidence or add new files. The dispute
itself remains open, but the bank response is final.

# `submit_evidence!`

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

Like `submit_evidence/3` but raises on failure.

# `update`

```elixir
@spec update(LatticeStripe.Client.t(), String.t(), map(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}
```

Updates a Dispute by ID.

This is the general-purpose update entry point for the underlying Stripe API.
It accepts any supported dispute update params, including raw `evidence` and
`submit` combinations for power users.

# `update!`

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

Like `update/4` but raises on failure.

# `update_evidence`

```elixir
@spec update_evidence(LatticeStripe.Client.t(), String.t(), map(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}
```

Stages dispute evidence without submitting it to the issuing bank.

This helper always sends `submit: false`, so it is impossible to
accidentally lock the dispute response while attaching evidence.

# `update_evidence!`

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

Like `update_evidence/4` but raises on failure.

---

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