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

Calculate tax for custom payment flows via Stripe's standalone Tax Calculations API.

## Lifecycle

Create a calculation with `create/3`, inspect it with `retrieve/3` or
`list_line_items/4`, then (within roughly **90 days**, before `expires_at`)
record tax by creating a `LatticeStripe.Tax.Transaction` from the calculation ID.
Calculations are ephemeral working snapshots — they are not durable tax records.

## 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 this Calculations API when you own
the payment flow and need explicit tax amounts before charging. Filing,
returns, and threshold monitoring are out of SDK scope.

## Usage

    {:ok, calc} =
      LatticeStripe.Tax.Calculation.create(client, %{
        "currency" => "usd",
        "customer_details" => %{
          "address" => %{
            "line1" => "123 Main St",
            "city" => "Seattle",
            "state" => "WA",
            "postal_code" => "98101",
            "country" => "US"
          },
          "address_source" => "shipping"
        },
        "line_items" => [
          %{
            "amount" => 1000,
            "reference" => "line-1",
            "tax_behavior" => "exclusive",
            "tax_code" => "txcd_99999999"
          }
        ]
      })

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

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

# `t`

```elixir
@type t() :: %LatticeStripe.Tax.Calculation{
  amount_total: integer() | nil,
  currency: String.t() | nil,
  customer: LatticeStripe.Customer.t() | String.t() | nil,
  customer_details: LatticeStripe.Tax.CustomerDetails.t() | nil,
  expires_at: integer() | nil,
  extra: map(),
  id: String.t() | nil,
  line_items: LatticeStripe.List.t() | nil,
  livemode: boolean() | nil,
  object: String.t(),
  ship_from_details: LatticeStripe.Tax.ShipFromDetails.t() | nil,
  shipping_cost: LatticeStripe.Tax.ShippingCost.t() | nil,
  tax_amount_exclusive: integer() | nil,
  tax_amount_inclusive: integer() | nil,
  tax_breakdown: [LatticeStripe.Tax.TaxBreakdown.t()] | nil,
  tax_date: integer() | nil
}
```

# `create`

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

Creates a Tax Calculation.

# `create!`

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

Like `create/3` but raises on failure.

# `from_map`

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

# `list_line_items`

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

Lists line items for a Tax Calculation.

# `list_line_items!`

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

Like `list_line_items/4` but raises on failure.

# `retrieve`

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

Retrieves a Tax Calculation by ID.

# `retrieve!`

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

Like `retrieve/3` but raises on failure.

---

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