> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.taxwire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout and shipment

> Quote tax at checkout and record the sale when the order ships

The full order flow: cart, checkout, payment and shipment.

```mermaid theme={null}
sequenceDiagram
    participant B as Buyer
    participant S as Your store
    participant T as Taxwire
    B->>S: Check out
    S->>T: POST /calculations
    T-->>S: tax_amount
    S->>B: Total with tax
    B->>S: Change the address, a coupon or an item
    S->>T: POST /calculations
    T-->>S: New tax_amount
    B->>S: Pay
    Note over S: Keep the lines and the tax charged
    Note over S: Order ships
    S->>T: POST /transactions (status: finalized)
    T-->>S: Saved transaction
    Note over S: Save the Taxwire id with the order
```

## 1. Quote tax at checkout

Call `POST /calculations` when the order is created, and again whenever it changes: a new address, a coupon, an added or removed item.

* **Send one line per item.** Each line has `quantity`, `unit_price`, a tax code in `product.tax_attributes`, the buyer's address in `customer.address` and the warehouse address in `fulfillment.address`.
* **Send shipping as its own line** with the tax code `ANCILLARY.SHIPPING`. Each state's rules decide whether it is taxed.
* **Send discounts on the lines they apply to**, as `discount_amount`. See [Discounts](https://apidocs.taxwire.com/api-reference/guides/discounts.md).
* **Send the full street address.** A ZIP code alone works, but it is less precise where a ZIP code crosses tax jurisdiction lines.
* **A line with no tax code** uses your account's default product tax code, or `TANGIBLE_PERSONAL_PROPERTY` if your account has none.

```json Request theme={null}
{
  "currency": "USD",
  "line_items": [
    {
      "id": "hoodie",
      "quantity": "2",
      "unit_price": "4000",
      "product": { "tax_attributes": ["TANGIBLE_PERSONAL_PROPERTY"] },
      "customer": { "address": { "line1": "200 N Spring St", "city": "Los Angeles", "state": "CA", "postal_code": "90012", "country": "US" } },
      "fulfillment": { "address": { "line1": "1 Warehouse Way", "city": "Ontario", "state": "CA", "postal_code": "91761", "country": "US" } }
    },
    {
      "id": "shipping",
      "quantity": "1",
      "unit_price": "800",
      "product": { "tax_attributes": ["ANCILLARY.SHIPPING"] },
      "customer": { "address": { "line1": "200 N Spring St", "city": "Los Angeles", "state": "CA", "postal_code": "90012", "country": "US" } },
      "fulfillment": { "address": { "line1": "1 Warehouse Way", "city": "Ontario", "state": "CA", "postal_code": "91761", "country": "US" } }
    }
  ]
}
```

The response gives the tax on each line, broken down by jurisdiction, and the order's total tax in `tax_amount`. Here the hoodies are taxed at Los Angeles's 10.25% and shipping isn't taxed, so `tax_amount` is `"820.000000"` (\$8.20).

> [!NOTE]
>
> Tax is only calculated in jurisdictions where you are registered. Elsewhere a line comes back with `0` tax. Until your registrations are set up in Taxwire, every quote returns `0`, so keep that in mind when testing.

## 2. Charge the buyer

Payment needs no Taxwire call. Charge the `tax_amount` from the last quote, and keep the lines, discounts and tax you charged with the order. If anything changed since the last quote, quote again first.

`tax_amount` can include a fraction of the currency's smallest unit, for example `"1293.75"` cents. Round the order's `tax_amount` once. Rounding each line and adding them up can be off by one unit.

## 3. Record the sale when it ships

Record the sale when it takes place for tax. For goods shipped to the buyer, that is usually when they ship, not when the buyer pays. If you're unsure for your products or states, ask us.

Send the shipped lines to `POST /transactions`, with the same body as the quote plus:

| Field | Value |
| - | - |
| `status` | `"finalized"` |
| `reference_id` | Your order number. It must be unique in your account. Avoid `/` in it: see [Retries and network failures](https://apidocs.taxwire.com/api-reference/faq.md#retries-and-network-failures). |
| `transaction_date` | When the order shipped, with a timezone, for example `"2026-12-07T10:15:00Z"`. |
| `tax_amount` | The tax you charged the buyer on these lines, in the smallest unit. |

`tax_amount` is the tax Taxwire reports on your returns, so send what you actually charged. Without it, Taxwire reports the tax it calculates.

The response is the saved transaction. **Save its `id` with your order**: refunds point to it as `parent_transaction_id`.

## Related

* [Transactions management](https://apidocs.taxwire.com/api-reference/guides/transactions.md): the `draft` status, which records a sale before it is finalized.
* [Retries and network failures](https://apidocs.taxwire.com/api-reference/faq.md#retries-and-network-failures)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.