Orders API

Order Returns and Exchanges

After an order is paid for, a buyer might return or exchange the order items. The resulting Order object provides the return or exchange details.

Order returns Permalink Get a link to this section

A return is where items are returned from the buyer to the seller and funds flow from the seller back to the buyer. A refund refers to money moving from the seller back to the buyer. 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 does not support itemized refunds. However, sellers can use Square first-party products (for example, Square POS) for itemized refunds.

  • Custom refund. A custom refund refers to refunding a specific order amount. First-party 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.

Itemized refunds Permalink Get a link to this section

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 is CUSTOM_AMOUNT.

  • Catalog information of the refunded line item, such as catalog_object_id and variation_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",
           ...
    }
  ]
  ...
}

Custom refunds Permalink Get a link to this section

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",
            ...
          }
        ]
      }
    ]
  }
}

Order exchanges Permalink Get a link to this section

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, there is no Orders API support for programmatically exchanging order items. A seller can only perform order exchanges using Square first-party products (such as Square POS). 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 example order 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 show 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.

{
  "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"
    }
  ]
}