Standard returns

The Refund API lets you reverse part or all of an existing order’s tax liability. When you issue a return, TaxCloud automatically references the original order’s tax calculation, including rates, TICs, and exemption status, and adjusts the appropriate amounts.

TaxCloud supports both full and partial returns, as well as multiple returns against the same order. Each return reduces the remaining returnable balance, and you can continue issuing returns until the cumulative total equals the original order amount.

For tax timing implications, backdated returns, and compliance considerations, see the Returns & Credits Overview. For credits not tied to an existing order, see Standalone Credits.

Before you begin

To issue a return, you need:

• The connectionID for your TaxCloud connection.
• The orderID of the order you want to return against.
• The order must be in a completed state (i.e., it has a completedDate).

Step 1: Retrieve the order

Before processing a return, retrieve the order to verify its current state, confirm which items are eligible for return, and check whether any previous returns have been issued.

$
curl -X GET "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/{orderId}" \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json"

Review the response to confirm:

• The order exists and has a completedDate.
• The items you intend to return are present in items.
• If the order has been previously returned, check the refunds array to understand what has already been returned.

Step 2: Issue a return

Submit a return request to the Refund API endpoint.

$
POST /tax/connections/{connectionId}/orders/refunds/{orderId}

Full return

To return the entire order, send an empty request body or omit the items array. TaxCloud will return all line items at their original quantities.

$
curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/refunds/{orderId}" \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{}'

Partial return

To return specific items, include only the items being returned with their itemID and quantity. TaxCloud calculates the tax adjustment based on the original tax rate applied to those items.

$
curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/refunds/{orderId}" \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "items": [
>
      {
>
        "itemId": "item-1",
>
        "quantity": 1
>
      }
>
    ]
>
  }'

Response

The API returns an array containing all returns issued against this order, not just the current one. This gives you a complete view of the order’s return history in every response.

1
[
2
  {
3
    "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a",
4
    "items": [
5
      {
6
        "index": 0,
7
        "itemId": "item-1",
8
        "price": 10.8,
9
        "quantity": 1,
10
        "tax": {
11
          "amount": 0.88
12
        },
13
        "tic": 0
14
      }
15
    ],
16
    "createdDate": "2025-02-15T14:30:00Z",
17
    "returnedDate": null
18
  }
19
]

Each return object in the array includes:

• items — The line items included in that specific return, with the tax amount that was reversed.
• createdDate — When the return was created in TaxCloud.
• returnedDate — The effective date of the return, if provided. See Backdated returns below.

Step 3: Issue additional returns

You can issue multiple returns against the same order. Each subsequent return request follows the same format, specifying the items and quantities being returned.

For example, if a customer initially returns one item and later returns a second item from the same order:

First return — return item-1:

$
curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/refunds/{orderId}" \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "items": [
>
      {
>
        "itemId": "item-1",
>
        "quantity": 1
>
      }
>
    ]
>
  }'

Second return — return item-2:

$
curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/refunds/{orderId}" \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "items": [
>
      {
>
        "itemId": "item-2",
>
        "quantity": 2
>
      }
>
    ]
>
  }'

The response to the second return includes both returns:

1
[
2
  {
3
    "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a",
4
    "items": [
5
      {
6
        "index": 0,
7
        "itemId": "item-1",
8
        "price": 10.8,
9
        "quantity": 1,
10
        "tax": {
11
          "amount": 0.88
12
        },
13
        "tic": 0
14
      }
15
    ],
16
    "createdDate": "2025-02-10T14:30:00Z",
17
    "returnedDate": null
18
  },
19
  {
20
    "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a",
21
    "items": [
22
      {
23
        "index": 1,
24
        "itemId": "item-2",
25
        "price": 24.99,
26
        "quantity": 2,
27
        "tax": {
28
          "amount": 4.06
29
        },
30
        "tic": 0
31
      }
32
    ],
33
    "createdDate": "2025-02-15T10:00:00Z",
34
    "returnedDate": null
35
  }
36
]

Cumulative limit

TaxCloud enforces that the total returned amount across all returns cannot exceed the original order total. If a return request would push the cumulative total over the order amount, the API returns an error. You do not need to track this limit yourself, TaxCloud validates it on every request.

Backdated returns

The returnedDate parameter is optional and should only be used when the return actually occurred on a date different from when you’re submitting it to TaxCloud.

$
curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/refunds/{orderId}" \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "items": [
>
      {
>
        "itemId": "item-1",
>
        "quantity": 1
>
      }
>
    ],
>
    "returnedDate": "2025-01-05T00:00:00Z"
>
  }'

Important

If the returnedDate falls within a previously filed tax period, this may trigger the need for an amended sales tax return. TaxCloud does not currently generate automatic alerts for this, you are responsible for tracking these cases and contacting TaxCloud support if an amendment is required.

Edge cases

Returns on tax-exempt orders

If the original order was fully tax-exempt (e.g., covered by an exemption certificate), no tax adjustment is processed since no tax was collected. The return is still recorded for transaction accuracy, but the tax amount in the response will be zero.

Returns on discounted items

When the original order included discounts, TaxCloud returns based on the actual post-discount price and tax that was calculated. If you need to return a prorated portion of a discounted item, submit the request with the fractional quantity that represents the discounted amount.

Returning the remaining balance

After one or more partial returns, you can return the remaining balance by sending an empty items array (just as you would for a full return). TaxCloud will return whatever items and quantities have not yet been returned.

Error handling

For the complete list of error responses, see the Refund API reference.

Best practices

• Always retrieve the order first to confirm its state and any existing returns before issuing a new one.
• Use the response array to track return history rather than maintaining your own ledger. Each response gives you the complete picture.
• Omit returnedDate unless the return genuinely occurred on a different date. Including it unnecessarily can complicate your filing timeline.
• Prefer standard returns over standalone credits whenever you have the original order ID. This maintains the strongest audit trail for compliance.