Refunds and Exchanges

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.
  • 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.

Link to section

Order refunds

A seller has two options to refund an order:

  • Itemized refund - A seller can refund a specific line item in an order.


    In the current implementation, the Refunds API doesn't support itemized refunds. However, sellers can use Square products (for example, Square Point of Sale) 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.

Link to section

Itemized refunds

For itemized refunds, the returns field provides the following information:

  • item_type, which is set to ITEM and indicates a line item. For custom refunds, it's CUSTOM_AMOUNT.
  • Catalog information of the refunded line item, such as catalog_object_id and variation_name.

An example refund order fragment is shown:

Link to section

Custom refunds

For custom refunds, the returns field has the item_type set to CUSTOM_AMOUNT and no other catalog item information.

Link to section

Order exchanges

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.


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_items shows the buyer purchased a small candle.
  • returns shows the buyer returned a large candle.
  • return_taxes shows the buyer gets $1.50 in taxes returned.
  • refunds shows the buyer gets a $6.75 refund.