Can the Square API refund one item? Itemized refunds, explained

An API refund on Square creates a return order with a single CUSTOM_AMOUNT line that names no item and breaks out no tax. Your app decides the amount, remembers which item it was for, puts the unit back in stock, and keeps the tax records Square's reports won't. On Flint the refund names the order's line item, and Flint computes the rest:

curl -X POST https://api.withflintpay.com/v1/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: refund-ord-1042-mug" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_1kmn0aExample",
    "reason": "defective_product",
    "line_items": [
      {"order_line_item_id": "li_1kmn0aExample", "quantity": 1}
    ]
  }'

Which path applies to you

What Square supports, by surface

The Orders API row is where most confusion starts. Square's returns page says an application "can use the Orders API for itemized refunds." A developer who tried every route in September 2026 found that Order.returns is read-only, so CreateOrder won't accept a return, and that RefundPayment has no order_id to link a refund to one. The Square staff reply said that sentence describes what an itemized refund looks like once it exists, and that the Point of Sale app can create one because "it drives an internal flow that isn't publicly exposed." Square staff have called itemized refunds a popular feature request since 2024.

The Square workaround: refund an amount, keep the item record yourself

Your app has to do four jobs Square does for itemized refunds in its own apps: work out the amount, refund it, record what it was for, and restock. Start from the order. Each line's total_money already includes its share of order discounts and its tax, so divide that by the quantity, in integer cents:

// Your code works out what one unit cost the buyer.
// total_money is read-only and already includes the line's share of
// order discounts and its tax. quantity is a string.
const { order } = await getOrder(orderId); // GET /v2/orders/{order_id}
const line = order.line_items.find((li) => li.uid === lineUid);

const lineTotal = Number(line.total_money.amount); // 3818 for three mugs
const units = Number(line.quantity);               // 3
const base = Math.floor(lineTotal / units);        // 1272
const remainder = lineTotal - base * units;        // 2 cents left over

// Give the leftover cents to the first units refunded, and check your own
// ledger so this unit hasn't been refunded already.
const alreadyRefunded = await refundedUnits(orderId, lineUid);
const amount = alreadyRefunded < remainder ? base + 1 : base; // 1273

Then refund that amount against the payment. The reason field, up to 192 characters, is the only place on the refund to note the item:

curl https://connect.squareup.com/v2/refunds \
  -X POST \
  -H "Square-Version: 2026-09-16" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "refund-order-1042-mug-unit-1",
    "payment_id": "PAYMENT_ID",
    "amount_money": {"amount": 1273, "currency": "USD"},
    "reason": "Mug arrived chipped (line 8uSwfzvUImn3IRrvciqlXC, 1 of 3)"
  }'

The refund comes back with an order_id for a new refund order. Its return line, abridged here, has no catalog item and says nothing about the mug:

"returns": [
  {
    "source_order_id": "ORIGINAL_ORDER_ID",
    "return_line_items": [
      {
        "quantity": "1",
        "item_type": "CUSTOM_AMOUNT"
      }
    ]
  }
]

That leaves three more pieces your app owns from now on:

• A refund ledger keyed by order, line, and unit, so the same item can't be refunded twice and partial refunds add up to the line total. Square only checks the payment's remaining balance.
• A restock call. A refund moves money only. Add the unit back with a BatchChangeInventory adjustment from UNLINKED_RETURN to IN_STOCK, which Square records as new stock rather than a return of that sale.
• Tax records. The return order shows no tax refunded, so the tax you gave back lives in your ledger, and your filing comes from there instead of Square's reports.

The other workaround: refund in Square, then read the refund order

When staff can do the refund, the Square staff reply in the forum suggests the reverse flow: staff refund the items in Square Point of Sale or the Dashboard, and your app syncs from the refund.created and refund.updated webhooks. To see which items came back, retrieve the refund, then the order in its order_id. That refund order, not the original sale, holds the itemized returns. Square staff noted in 2025 that "not all refunds will be itemized," so the code has to handle CUSTOM_AMOUNT returns as well. This keeps the tax and item detail right, and it means your own app can never issue the refund.

The four places hand-built Square item refunds go wrong