# How do I get an API refund to keep the item category and the tax?

**URL:** <https://developer.squareup.com/forums/t/how-do-i-get-an-api-refund-to-keep-the-item-category-and-the-tax/27486>\
**Category:** Questions\
**Tags:** refunds-api\
**Created:** [September 3, 2026, 5:34pm UTC](https://developer.squareup.com/forums/t/how-do-i-get-an-api-refund-to-keep-the-item-category-and-the-tax/27486 "2026-09-03T17:34:35Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![BKSVL](https://avatars.discourse-cdn.com/v4/letter/b/bc8723/32.png) [@BKSVL](https://developer.squareup.com/forums/u/BKSVL)\
**Post date:** [September 3, 2026, 5:34pm UTC](https://developer.squareup.com/forums/t/how-do-i-get-an-api-refund-to-keep-the-item-category-and-the-tax/27486/1 "2026-09-03T17:34:35Z")

</div>

I manage a bowling center and wrote a small internal app that rings our weekly  
league dues into Square. It creates an order against the league’s item variation  
with `auto_apply_taxes`, then takes a cash payment. Those sales report fine,  
right category and right tax.

The trouble is reversing one. If somebody enters a night wrong, we call  
`POST /v2/refunds` against the payment for the full amount. The money goes back  
correctly, but the return Square generates comes out as:

```json
{
  "item_type": "CUSTOM_AMOUNT",
  "quantity": "1",
  "total_money": { "amount": 263921, "currency": "USD" }
}

```

and `return_amounts.tax_money` is `$0.00`.

When one of our people refunds the same sort of sale from the POS instead, we  
get `item_type: ITEM` with `catalog_object_id` and `source_line_item_uid`  
populated and the tax broken out properly. So the POS can obviously do this. I  
just can’t figure out how to ask for it over the API.

Two problems it causes here. The small one is that the refund doesn’t land in  
the league category, so that category reads high all month.

The bigger one is the tax. A $2,639.21 sale charged $178.41 of sales tax, and  
the return credits none of it back. I have seven of these in a single month,  
$894.18 of tax we charged on refunds that Square’s  
reporting still counts as collected.

Things I’ve already tried:

- Building the return order myself with `CreateOrder`. `Order.returns` is  
`readOnly` in the spec, so it won’t accept one.
- Looking for a way to attach a refund to a return order I’d made.  
`RefundPaymentRequest` has no `order_id` and no line item fields.
- The Refunds and Exchanges page says “**your application can use the Orders API  
for itemized refunds**”, which is what sent me looking in the first place, but I  
can’t find an endpoint that actually does it. [Refunds and Exchanges](https://developer.squareup.com/docs/orders-api/order-returns-exchanges)

So am I missing an endpoint or a parameter somewhere? And if this really isn’t  
possible today, is there any chance of either taking line item detail on  
`RefundPayment`, or at minimum apportioning tax onto the generated  
`CUSTOM_AMOUNT` return? The second one by itself would fix the part that  
actually costs money.

Production, US, `Square-Version: 2024-10-17`, plain HTTP calls, no SDK. Happy to  
send order and refund IDs over to staff if that helps.

---

<div class="post-metadata">

**Author:** ![ashley-square](https://avatars.discourse-cdn.com/v4/letter/a/5f9b8f/32.png) [@ashley-square](https://developer.squareup.com/forums/u/ashley-square)\
**Post date:** [September 8, 2026, 5:14pm UTC](https://developer.squareup.com/forums/t/how-do-i-get-an-api-refund-to-keep-the-item-category-and-the-tax/27486/3 "2026-09-08T17:14:26Z")

</div>

Unfortunately itemized returns aren’t possible via the API today.

`POST /v2/refunds` is amount-based only: no `order_id`, no line item fields. So the return we generate is always a single `CUSTOM_AMOUNT` with `tax_money` at zero. Both things you tried are correctly ruled out. `Order.returns`really is `readOnly`, and there’s no way to attach a RefundPayment to a return order you built. The POS can do it because it drives an internal flow that isn’t publicly exposed.

That doc sentence describes the read shape / what `returns` looks like when an itemized refund already exists, not a write endpoint. The common pattern for apps in your spot is to have staff do refunds in Square POS, and have the app listen to `refund.created` / `refund.updated` webhooks to stay in sync for reporting. You’d keep your own ledger as the source of truth for month-end and treat our report as cash movement. I know that partly defeats the app you wrote, but it’s the only path that gets you `item_type: ITEM` with tax broken out.

I’ll flag this with our product team again as itemized returns/refunds is one of our top feature requests at the moment.