Applies to: Orders API | Refunds API
Learn how refunds and exchanges are supported in the Orders API.
After an order is paid for, a buyer might return one or more order items. In a return scenario, a seller can offer the buyer one of the following options:
- A refund of some or all of the purchase price, where money flows from the seller back to the buyer.
- A return of individual line items and the purchase price of those line items.
- An exchange for a more suitable item. Depending on the exchange, the seller might refund money to the buyer or the buyer might owe money to the seller. In a like-for-like exchange, no money movement is required.
The resulting Order object provides the return or exchange details.
A seller has two options to refund an order:
Itemized refund - A seller can refund a specific line item in an order.
Note
In the current implementation, the Refunds API doesn't support itemized refunds. However, your application can use the Orders API for itemized refunds.
Custom refund - A custom refund refers to refunding a specific order amount. Square products and the Refunds API both support custom refunds.
Both the itemized refund and custom refund create a return order (an Order object). An example skeleton return object is shown:
{ "order":{ "id":"j7CWK5PozTAPsfm2XlGPKPzeV", ... "returns":[ ... ], "return_amounts":[ ... ], "refunds":[ ... ] } }
The information in the returns field (a collection of OrderReturn objects) varies for itemized and custom refunds.
For itemized refunds, the returns field provides the following information:
item_type, which is set toITEMand indicates a line item. For custom refunds, it'sCUSTOM_AMOUNT.- Catalog information of the refunded line item, such as
catalog_object_idandvariation_name.
An example refund order fragment is shown:
{ "order": { "id": "j7CWK5PozTAPsfm2XlGPKPzeV", ... }, "returns": [ { "source_order_id": "L5tvBZ6VwJ0XBMJ0MhTmsqjeV", "return_line_items": [ { "uid": "D2B3E994-BDBC-437E-A692-CBD3CA38494D", "source_line_item_uid": "36EFB2B5-4B53-4258-9E95-7D315753DFD8", "name": "Tea", "quantity": "1", "catalog_object_id": "FUNBA4YDZZOE2BLDWNHWLUI6", "catalog_version": 1598022506033, "variation_name": "Mug", "item_type": "ITEM", ... } ] ... }
For custom refunds, the returns field has the item_type set to CUSTOM_AMOUNT and no other catalog item information.
{ "order": { "id": "XBcMoV9ryMGH6CF62lkze04eV", ... "returns": [ { "source_order_id": "9ImSxCWZcr7aQVwoEVmN1o2eV", "return_line_items": [ { "uid": "itemization:0F6B7865-70E2-4B14-8DF8-345A31B62735", "quantity": "1", "item_type": "CUSTOM_AMOUNT", ... } ] } ] } }
A buyer might choose to exchange an order line item. The resulting order reports the exchange as a new line item and a return in the same transaction.
Note
In the current implementation, the Orders API doesn't support programmatically exchanging order items. A seller can only perform order exchanges using Square products (such as Square Point of Sale). However, orders that result from exchanges can be accessed using the Orders API (for example, using the SearchOrder endpoint).
Depending on the exchange, the seller might refund money to the buyer, the buyer might owe money to the seller, or it might be an even exchange where no money movement is required. The following order example shows a buyer exchanging a large candle ($15) for a small candle ($10). In this case, the seller owes the buyer a refund. Note the following highlights in this order:
line_itemsshows the buyer purchased a small candle.returnsshows the buyer returned a large candle.return_taxesshows the buyer gets $1.50 in taxes returned.refundsshows the buyer gets a $6.75 refund.
{ "id": "9MuB7WhEuxpuHtzbdrDqXIkeV", "location_id": "X9XWRESTK1CZ1", "line_items": [ { "uid": "C934D5A2-A33F-48BA-BB6E-E1408DDC6179", "catalog_object_id": "CV7HSSVBAL6H7GLGBG3SAHNX", "catalog_version": 1633235632885, "quantity": "1", "name": "Lavender candle", "variation_name": "Lavender candle (small)", "base_price_money": { "amount": 1000, "currency": "USD" }, "total_tax_money": { "amount": 250, "currency": "USD" }, "total_discount_money": { "amount": 0, "currency": "USD" }, "total_money": { "amount": 1250, "currency": "USD" }, "variation_total_price_money": { "amount": 1000, "currency": "USD" }, "applied_taxes": [...], "item_type": "ITEM" } ], "taxes": [...], "created_at": "2021-10-03T04:35:51.000Z", "updated_at": "2021-10-03T04:35:51.000Z", "state": "COMPLETED", "total_tax_money": { "amount": 250, "currency": "USD" }, ... "total_money": { "amount": 1250, "currency": "USD" }, "returns": [ { "source_order_id": "3V83oQoa3XDu90I5AW5wkUkeV", "return_line_items": [ { "uid": "09219A1A-F02B-496E-BD55-16689A0EFF5E", "source_line_item_uid": "29B7C6B4-8F61-4749-BB12-9E86C98EDE25", "name": "Lavender candle", "quantity": "1", "catalog_object_id": "Z7JOD6P746IBPOKKJJ4K2CEF", "catalog_version": 1633235632885, "variation_name": "Lavender candle (Large)", "item_type": "ITEM", "applied_taxes": [...], "base_price_money": { "amount": 1500, "currency": "USD" }, ... "total_tax_money": { "amount": 375, "currency": "USD" }, "total_money": { "amount": 1875, "currency": "USD" } } ], "return_taxes": [...] } ], "return_amounts": { "total_money": { "amount": 1875, "currency": "USD" }, "tax_money": { "amount": 375, "currency": "USD" }, ... "net_amounts": { "total_money": { "amount": -625, "currency": "USD" }, "tax_money": { "amount": -125, "currency": "USD" }, ..., "refunds": [ { "id": "IPATbcVj03b4AN3dHxw5S", ... "transaction_id": "3V83oQoa3XDu90I5AW5wkUkeV", "tender_id": "xgwQNEoBo9IcWZwVmgjxclxuuaB", ... "reason": "Test", "amount_money": { "amount": 625, "currency": "USD" }, "status": "APPROVED" } ] }