> This page is for version v6.0 (default).
> For other versions, use one of these documentation indexes:
> - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt
> - v5.0: https://docs.zip.tax/v-5-0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.zip.tax/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server.

# Refunds

Issue a refund against an order you previously recorded with
[Orders](orders). Omit `items` to refund the whole order, or include specific
items to issue a partial refund. The operation acts on a single
[TaxCloud-connected merchant](taxcloud-connected-merchants) identified by
`merchantId`.

Uses `POST` and the `X-API-KEY` header. See [Merchant Transactions](transactions)
for the shared conventions, error shapes, and usage rules.

> **Info**
>
> Refunds are not available for [self-managed merchants](self-managed-merchants) —
> `refund/create` returns `403`. A refund amends a recorded order, and self-managed
> merchants have no recorded orders.

## Endpoint

```http
POST https://api.zip-tax.com/merchant/refund/create
```

## Request body

| Field          | Type                       | Required | Description                                                                                                                                                         |
| -------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantId`   | string (UUID)              | Yes      | The connected merchant. Must be owned by the calling account. Consumed for routing and not forwarded.                                                               |
| `orderId`      | string                     | Yes      | The order to refund, as supplied when the order was created. Consumed for routing and not forwarded in the refund payload.                                          |
| `items`        | array                      | No       | The items to refund. Omit or send an empty array for a **full** refund; include items for a **partial** refund. Each entry is `{ "itemId": "...", "quantity": 1 }`. |
| `returnedDate` | string (RFC3339 date-time) | No       | Include only if this return amends a previously filed sales tax return; providing it triggers an Amended Sales Tax Return. Not typically recommended.               |
| `batchId`      | string                     | No       | Optional batch ID for grouping related refunds.                                                                                                                     |

### Refund item object

| Field      | Type                  | Required | Description                                                                                                   |
| ---------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `itemId`   | string (1–50 chars)   | Yes      | The `itemId` of the line item to refund. Must match an `itemId` from the original order.                      |
| `quantity` | number (0–99999.9999) | Yes      | The quantity of the item to refund. May be fractional and must not exceed the quantity on the original order. |

Refund prices and tax amounts are calculated automatically from the order —
you do not send them. If the order had discounts applied, refunds use the
discounted prices (the amounts the customer actually paid).

## Examples

#### Full refund

```bash
curl -X POST "https://api.zip-tax.com/merchant/refund/create" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
    "orderId": "order-2026-000123"
  }'
```

#### Partial refund

```bash
curl -X POST "https://api.zip-tax.com/merchant/refund/create" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
    "orderId": "order-2026-000123",
    "items": [
      { "itemId": "sku-1001", "quantity": 1 }
    ]
  }'
```

## Response

Returns the recorded refund:

| Field                | Type                       | Description                                                                                                                 |
| -------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `connectionId`       | string                     | The TaxCloud connection the refund was recorded under.                                                                      |
| `createdDate`        | string (RFC3339 date-time) | When the refund was created.                                                                                                |
| `returnedDate`       | string (RFC3339 date-time) | When the refund took effect.                                                                                                |
| `batchId`            | string                     | Batch ID grouping this refund, if one was supplied.                                                                         |
| `items[].index`      | integer                    | Zero-based position of the item within the refund.                                                                          |
| `items[].itemId`     | string                     | The refunded line item, matching the original order.                                                                        |
| `items[].price`      | number                     | The unit price refunded, calculated automatically from the order. Reflects discounted amounts when the order had discounts. |
| `items[].quantity`   | number                     | The quantity refunded.                                                                                                      |
| `items[].tic`        | integer                    | Taxability Information Code of the refunded item.                                                                           |
| `items[].tax.amount` | number                     | The tax amount refunded, calculated proportionally from the order's tax.                                                    |

```json
{
  "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a",
  "createdDate": "2026-07-14T09:30:00Z",
  "returnedDate": "2026-07-14T09:30:00Z",
  "items": [
    {
      "index": 0,
      "itemId": "sku-1001",
      "price": 49.99,
      "quantity": 1,
      "tic": 0,
      "tax": { "amount": 3.87 }
    }
  ]
}
```

> **Warning**
>
> Refunds are **never** retried automatically, and you should not retry them
> blindly: a duplicate refund is a financial incident. If a refund call times out
> or returns `502`/`504`, first confirm whether it succeeded by fetching the order
> with [`order/get`](orders#get-an-order) using `"expand": "refunds"`, then retry
> only if the refund is not present.

## Related

#### [Orders](orders)

Record and retrieve the orders you refund against.

#### [Merchant Transactions](transactions)

Shared conventions, errors, and usage.