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)

Example Request and Response (Full)

Request (Full)

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

1
{
2
  "apiLoginID": "XXXXXXX",
3
  "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
4
  "orderID": "order23",
5
  "returnedDate": "2025-08-01"
6
}

Response (Success)

1
{
2
  "ResponseType": 3,
3
  "Messages": []
4
}

Response (error)

1
{
2
  "ResponseType": 0,
3
  "Messages": [
4
    {
5
      "ResponseType": 0,
6
      "Message": "This Order ID (order23) has already been returned."
7
    }
8
  ]
9
}

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

1
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)

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:

1
{
2
  "apiLoginID": "XXXXXXX",
3
  "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
4
  "orderID": "order23",
5
  "returnedDate": "2025-08-01",
6
  "cartItems": [
7
    {
8
      "Index": 0,
9
      "ItemID": "33764",
10
      "Price": 19.95,
11
      "Qty": 0.2
12
    }
13
  ]
14
}

Response (Partial Success)

1
{
2
  "ResponseType": 3,
3
  "Messages": []
4
}

Response (Error)

1
{
2
  "ResponseType": 0,
3
  "Messages": [
4
    {
5
      "ResponseType": 0,
6
      "Message": "This Order ID (order23) has already been returned."
7
    }
8
  ]
9
}

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.