# `LatticeStripe.Tax.Settings`
[🔗](https://github.com/szTheory/lattice_stripe/blob/v2.2.2/lib/lattice_stripe/tax/settings.ex#L1)

Account-level Stripe Tax configuration singleton.

Tax Settings is a **singleton** — there is no resource ID. The only operations
are `retrieve/2` and `update/3` against fixed paths on `/v1/tax/settings`.

## Defaults and Calculation

The `defaults` field holds account-wide fallbacks such as `tax_code` and
`tax_behavior`. When line items in `LatticeStripe.Tax.Calculation.create/3`
omit those fields, Stripe applies the settings defaults.

## Relationship to other tax surfaces

This module is **not** `LatticeStripe.Invoice.AutomaticTax`. Automatic tax on
Invoices, Subscriptions, and Quotes is configured via nested `automatic_tax`
settings on those Billing resources. Use Tax Settings for account-wide
Stripe Tax configuration that applies to the Calculations API and
registrations.

Pass `stripe_account: "acct_..."` in `opts` on `retrieve/2` and `update/3`
for connected accounts (same semantics as `LatticeStripe.Balance.retrieve/2`).

## Usage

    {:ok, settings} = LatticeStripe.Tax.Settings.retrieve(client)

    {:ok, settings} =
      LatticeStripe.Tax.Settings.update(client, %{
        "defaults" => %{
          "tax_behavior" => "exclusive",
          "tax_code" => "txcd_99999999"
        }
      })

Once a settings field is set, Stripe does not support unsetting it via the
API — you can only change values. Check `status` and `status_details` for
whether Tax is active in your jurisdictions.

See [Standalone Tax API](guides/tax.md) for the canonical calculate → record → reverse workflow.

See [Stripe Tax Settings](https://docs.stripe.com/api/tax/settings).

# `t`

```elixir
@type t() :: %LatticeStripe.Tax.Settings{
  defaults: LatticeStripe.Tax.Settings.Defaults.t() | nil,
  extra: map(),
  head_office: LatticeStripe.Tax.Settings.HeadOffice.t() | nil,
  livemode: boolean() | nil,
  object: String.t(),
  status: atom() | String.t() | nil,
  status_details: LatticeStripe.Tax.Settings.StatusDetails.t() | nil
}
```

# `retrieve`

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

Retrieves the Stripe Tax Settings singleton.

Sends `GET /v1/tax/settings` and returns `{:ok, %Settings{}}`.

Pass `stripe_account: "acct_..."` in `opts` for connected accounts.

# `retrieve!`

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

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

# `update`

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

Updates Stripe Tax Settings.

Sends `POST /v1/tax/settings` with the raw params map.

# `update!`

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

Like `update/3` but raises on failure.

---

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