This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Refund information in Order objects

This section provides examples of the way that refund information appears in Toast API Order objects. New refund functionality allows restaurant employees to perform refunds from a Toast POS device. Previously, restaurant employees could void items from checks using a POS device but could only perform payment refunds from Toast administration back end. In the new functionality, refunds performed on a Toast POS device will affect order information in the same way that refunds performed on the Toast administration back-end do. Both POS device refunds and Toast administration back-end refunds will result in the Order object refund information shown in the examples in this section.

The new refund functionality will be available for restaurant locations to use in version 2.46 of the Toast POS mobile application. Version 2.46 of the Toast POS application is expected to be available in Toast platform restaurant locations starting on 2021-01-27.

The following examples show an Order object before and after a refund transaction.

Order object before a refund transaction

{
  "entityType": "Order",
 
  [contents omitted]

  "checks": [
    {
 
      [contents omitted]

      "payments": [
        {
 
          [contents omitted]

          "refundStatus": "NONE",1
 
          [contents omitted]

          "refund": null2
        }
      ],
 
     [contents omitted]

      "selections": [
        {
 
         [contents omitted]

          "refundDetails": null,3
 
         [contents omitted]

        }
      ],
 
      [contents omitted]

    }
  ],
 
  [contents omitted]

}

1

Indicates the effect of a refund on the payment, if any refund applies to the payment. In this example, there is no refund related to the payment.

2

Provides information about a refund, if any refund applies to the payment. In this example, there is no refund related to the payment. See an example of the refund value after a refund transaction in Order object after a refund transaction.

3

Provides information about refunded payment amounts for the item. See an example of the refundDetails value after a refund transaction in Order object after a refund transaction.


Order object after a refund transaction

{
  "entityType": "Order",
 
  [contents omitted]

  "checks": [
    {
 
     [contents omitted]

      "payments": [
        {
 
         [contents omitted]

          "refundStatus": "FULL",1
 
         [contents omitted]

          "refund": {
            "refundAmount": 9.63,2
            "tipRefundAmount": 0,3
            "refundDate": "2021-01-12T16:36:30.641+0000",4
            "refundBusinessDate": 20210112,5
            "refundTransaction": {6
              "guid": "4d35fe7b-2825-47a0-9001-526ae1158ab0",
              "entityType": "RefundTransaction"
            }
          }
        }
      ],
 
      [contents omitted]

      "selections": [
        {
 
         [contents omitted]

          "refundDetails": {
            "refundAmount": 9.00,7
            "taxRefundAmount": 0.63,8
            "refundTransaction": {9
              "guid": "4d35fe7b-2825-47a0-9001-526ae1158ab0",
              "entityType": "RefundTransaction"
            }
          },
 
         [contents omitted]

        }
      ],
 
      [contents omitted]

    }
  ],
 
  [contents omitted]

}

1

Indicates the effect of a refund on the payment, if any refund applies to the payment. In this example, the entire payment amount has been refunded.

2

The amount of the refund excluding the tip.

3

The amount of the tip refund.

4

The date and time the refund was made.

5

The restaurant business date (in yyyyMMdd format) the refund was made.

6

An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.

7

The value of the menu item or service charge (excluding taxes) being refunded. Includes the value of any nested modifier options that increased the price of the item or modifier option (an increased charge for the modifier option).

8

The tax amount being refunded.

9

An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.