> This page is for version API v1.
> For other versions, use one of these documentation indexes:
> - API v3 (default): https://docs.taxcloud.com/api-v-3/llms.txt
> - API v1: https://docs.taxcloud.com/api-v-1/llms.txt

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

# Returned API Basics

The Returned API is how you notify TaxCloud when an order has been refunded or canceled. This ensures the refunded sales tax is properly accounted for in reporting and credits.

There are two main ways to use the Returned API:

* Full Returns – refund the entire order by simply providing the *OrderID* of the previously completed order.
* Partial Returns – refund specific line items or fractional quantities by providing the complete array of CartItems from the original order.

## Full Returns

The *Full* use of our *Returned API* requires only a single *OrderID* parameter (in addition to API Credentials). In this mode, that's all there is to it.

### Parameters (Full)

| Parameter | Required | Description | Example |
| :---- | :---- | :---- | :---- |
| apiLoginID | ✔ | Your unique 7 or 8 character API ID | XXXXXXX |
| apiKey | ✔ | Your unique API KEY | XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
| orderID | ✔ | The immutable Order identifier used by your order management or e-commerce system to idenitify unique orders. | order23 |
| returnedDate | ✔ | Effective date of the return **CAUTION: [See Note](https://app.taxcloud.com/developer#important-note-regarding-the-returneddate-parameter)** | 08/27/2019 |

### Example Request and Response (Full)

#### Request (Full)

HTTPS POST api.taxcloud.net/1.0/TaxCloud/Returned

```curl
{
  "apiLoginID": "XXXXXXX",
  "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "orderID": "order23",
  "returnedDate": "2025-08-01"
}
```

#### Response (Success)

```curl
{
  "ResponseType": 3,
  "Messages": []
}
```

#### Response (error)

```curl
{
  "ResponseType": 0,
  "Messages": [
    {
      "ResponseType": 0,
      "Message": "This Order ID (order23) has already been returned."
    }
  ]
}
```

## Partial Returns

Partial returns use the same endpoint, but include a cartItems array. This allows you to return specific items or quantities from the original order.

When performing Partial (item-level) returns, our *Returned API* signature is identical to our *Lookup API* signature. This means:

* All returned items are processed as negative quantities relative to the original lookup cart items.
* When issuing a return using the Returned API, it’s critical that the return reflects the **original transaction** as captured through the Lookup API. To ensure compliance with **Generally Accepted Accounting Principles (GAAP)**, the only change permitted in a returned API call is to the Qty (quantity) field. Do not modify any fields except Qty.
* Items not being returned can be omitted or set to Qty: 0.
* *CartItems* being returned should have

```curl
Qty: [n]
```

Where *\[n\]* is a decimal not exceeding the original *Qty* from *Lookup*

**Example 1:**

If your customer returned a pair of shoes (e.g., ItemID: "33764"), but none of the other items from the original order, you would return the *CartItem* object for ItemID 33764, with a Qty: 1, returning the entire item. All other CartItems should have a Qty: 0, or can simply be omitted from the *Returned API* call.

**Example 2:**  
If your customer service team wanted to issue a 20% discount to a customer for a particular item, the *Returned API* should be called with the *CartItem* object for ItemID 33764, with a Qty: 0.2 (returned CartItems are recieved as negative quantities relative to the original quantities).

## Parameters (Partial)

| Parameter | Required | Description | Example |
| :---- | :---- | :---- | :---- |
| apiLoginID | ✔ | Your unique 7 or 8 character API ID | XXXXXXX |
| apiKey | ✔ | Your unique API KEY | XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
| orderID | ✔ | The immutable Order identifier used by your order management or e-commerce system to idenitify unique orders. | order23 |
| cartItems |  | *CartItem* array of items being returned (items not being returned can be omitted). | *see example below* |
| returnedDate | ✔ | Effective date of the return **CAUTION: [See Note](https://app.taxcloud.com/developer#important-note-regarding-the-returneddate-parameter)** | 08/27/2019 |

### Example Request and Response (Partial)

#### Request (Partial)

HTTPS POST api.taxcloud.net/1.0/TaxCloud/Returned

This request issues a 20% return on one item from the order:

```curl
{
  "apiLoginID": "XXXXXXX",
  "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "orderID": "order23",
  "returnedDate": "2025-08-01",
  "cartItems": [
    {
      "Index": 0,
      "ItemID": "33764",
      "Price": 19.95,
      "Qty": 0.2
    }
  ]
}
```

#### Response (Partial Success)

```curl
{
  "ResponseType": 3,
  "Messages": []
}
```

### Response (Error)

```curl
{
  "ResponseType": 0,
  "Messages": [
    {
      "ResponseType": 0,
      "Message": "This Order ID (order23) has already been returned."
    }
  ]
}
```

## Key Rules for Compliance

* Always reference the original transaction from Lookup.
* Only adjust the Qty field when issuing a return.
* Do not set negative prices; TaxCloud interprets reduced quantities as returns.