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

# Refunds

> Record full and partial refunds of a recorded sale

A refund, return or cancellation after an order has shipped is a new transaction with `type: credit`, linked to the original sale with `parent_transaction_id`. Don't update the original sale: once it is `finalized`, its line items can't be changed.

This also covers chargebacks, recalls and items found missing after delivery: each is a credit for the affected lines.

```mermaid theme={null}
sequenceDiagram
    participant B as Buyer
    participant S as Your store
    participant T as Taxwire
    B->>S: Return some items
    S->>T: POST /calculations (refunded lines, sale's date)
    T-->>S: tax_amount to refund
    S->>B: Refund the items and the tax
    S->>T: POST /transactions (type: credit, parent_transaction_id)
    T-->>S: Saved credit
```

## Full refund

Send `POST /transactions` without `line_items`:

```json theme={null}
{
  "type": "credit",
  "status": "finalized",
  "parent_transaction_id": "txn_01J...",
  "reference_id": "ORD-1001-R1",
  "currency": "USD",
  "tax_amount": "820"
}
```

Taxwire copies the sale's line items and discounts onto the credit. **Leave `line_items` out entirely**: an empty list (`[]`) copies nothing.

Send the tax you refunded as `tax_amount`. If the sale was recorded with a `tax_amount`, the credit doesn't copy it, so the credit needs its own.

## Partial refund

1. **Quote the refunded lines** with `POST /calculations`. Use the same addresses, tax codes and discounts as on the sale, and set `transaction_date` to the sale's `transaction_date` so the same rates apply. Include any refunded shipping as an `ANCILLARY.SHIPPING` line. Don't prorate the sale's tax.
2. **Refund the buyer** that tax.
3. **Record the credit** with only the refunded lines. Returning one of the two hoodies from the [checkout example](https://apidocs.taxwire.com/api-reference/flows/checkout.md#1-quote-tax-at-checkout):

```json theme={null}
{
  "type": "credit",
  "status": "finalized",
  "parent_transaction_id": "txn_01J...",
  "reference_id": "ORD-1001-R2",
  "currency": "USD",
  "tax_amount": "410",
  "line_items": [
    {
      "id": "hoodie",
      "quantity": "1",
      "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" } }
    }
  ]
}
```

## Rules for every credit

* **Amounts are positive.** `type: credit` is what marks them as a refund.
* **Give each credit its own `reference_id`**, for example `-R1`, `-R2` for successive refunds on one order.
* **Send the tax you refunded as `tax_amount`.** It is the amount Taxwire reports.
* **Date the credit when the refund happens.** Leave `transaction_date` out (it defaults to now) or send the refund's date. A credit is reported in the period of its own date, so a refund in a later quarter reduces that quarter's return. Don't date a credit before its sale: Taxwire flags it with a warning.
* **Link credits to a finalized sale.** A credit against a `draft` sale is refused with `422` and `credit_remainder_unknown`. See the [FAQ](https://apidocs.taxwire.com/api-reference/faq.md#refunds).
* **Use the sale's currency.** A credit with line items in another currency is refused with `422`. A full refund always takes the sale's currency.
* **Keep refunds within the sale.** Taxwire doesn't stop credits from adding up to more than the sale, so your system needs to.

## Related

* [Transactions management](https://apidocs.taxwire.com/api-reference/guides/transactions.md#create-credit-transactions)
* [Cancellations](https://apidocs.taxwire.com/api-reference/flows/cancellations.md): before shipping, and sales recorded by mistake.


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