> ## 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.

# Transaction flows

> Which Taxwire call to make at each step of an order

These pages map each step of an online order to the Taxwire call it needs. Start here, then follow the flow for your case:

* [Checkout and shipment](https://apidocs.taxwire.com/api-reference/flows/checkout.md): quote tax at checkout, record the sale when it ships.
* [Cancellations](https://apidocs.taxwire.com/api-reference/flows/cancellations.md): an order cancelled before it ships, and a sale recorded by mistake.
* [Refunds](https://apidocs.taxwire.com/api-reference/flows/refunds.md): full and partial refunds of a recorded sale.
* [Pre-orders](https://apidocs.taxwire.com/api-reference/flows/prepayments.md): orders paid now and shipped later.

## The order, end to end

Blue boxes are Taxwire calls. Dotted lines are quotes, which save nothing. Thick lines record a transaction.

```mermaid theme={null}
flowchart TD
    A[Checkout, and every change to the order] -. quote .-> Q1(["POST /calculations"])
    A --> B[Payment]
    B --> C{What happens next?}
    C -- "cancelled before shipping" --> X[Cancellation]
    X -. "quote the cancelled lines" .-> Q2(["POST /calculations"])
    C -- ships --> S[Shipment]
    S == "record the sale" ==> T1(["POST /transactions<br/>type: sale"])
    S --> R[Refund or return]
    R -. "quote the refunded lines" .-> Q3(["POST /calculations"])
    R == "record the credit" ==> T2(["POST /transactions<br/>type: credit"])
    classDef taxwire fill:#e6f0fb,stroke:#006ad4,color:#00336b
    class Q1,Q2,Q3,T1,T2 taxwire
```

## Quoting and recording

Every flow uses two calls:

| Call | What it does | Saves anything? |
| - | - | - |
| `POST /calculations` | Quotes the tax for an order. | No. Call it as often as you like. |
| `POST /transactions` | Records a sale (`type: sale`) or a refund (`type: credit`). Recorded transactions are what Taxwire reports and files. | Yes. |

Quote whenever the order changes. Record once, when the sale is complete. A quote that is never recorded has no effect on your returns.

## Order steps at a glance

| Order step | Call | Notes |
| - | - | - |
| Cart saved | None | A cart is not an order. |
| Checkout, and every change to the order | `POST /calculations` | Show the returned `tax_amount` to the buyer. |
| Payment | None | Charge the tax from the last quote. |
| Cancelled before shipping | None, or `POST /calculations` | Nothing was recorded. Quote the cancelled lines if you need the tax to refund. |
| Order ships | `POST /transactions`, `status: finalized` | Save the Taxwire `id` with your order. |
| Refund or return after shipping | `POST /transactions`, `type: credit` | Link it to the sale with `parent_transaction_id`. |
| Sale recorded by mistake | `POST /transactions/{id}`, `{"status": "void"}` | Only while the sale's period is unfiled. |
| Delivery, settlement, payout | None | These don't change the tax. |

> [!NOTE]
>
> The API is synchronous and sends no webhooks. The response to `POST /transactions` is the saved transaction. See [Retries and network failures](https://apidocs.taxwire.com/api-reference/faq.md#retries-and-network-failures) for what to do when a request fails or times out.

## Request basics

Every request uses the base URL `https://api.taxwire.com` and these headers:

```txt theme={null}
Content-Type: application/json
X-API-Key: <your API key>
Taxwire-Version: hydrogen.2025-04-15
```

Amounts are strings in the currency's smallest unit. `"1000"` is \$10.00 in USD, and `"45000"` is ₩45,000 in KRW, which has no smaller unit.


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