{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/toast-tab/refs/heads/main/json-structure/orders-order-structure.json",
  "name": "Order",
  "description": "A Toast platform order is composed of one or more checks. Each check has \none or more menu item selections.\n\nThe `externalId` value for an order must be unique. If you submit an order\nwith an `externalId` that already exists for another order, the request\nwill fail. You can use this behavior to implement idempotent order\nsubmission by always providing a consistent `externalId` for each unique\norder attempt.\n",
  "type": "object",
  "definitions": {
    "ExternalReference": {
      "type": "object",
      "description": "A wrapper object with fields that allow reference to a Toast platform entity by Toast GUID or a partner's identifier.",
      "allOf": [
        {
          "$ref": "#/$defs/ToastReference"
        },
        {
          "type": "object",
          "properties": {
            "externalId": {
              "description": "External identifier string that is prefixed by the naming authority. You can use the orders API to set an `externalId` for an order and then GET the order with that `externalId`.",
              "type": "string"
            }
          }
        }
      ],
      "name": "ExternalReference"
    },
    "Check": {
      "type": "object",
      "description": "Represents a single check within an order.\n\nThe `externalId` value for a check must be unique. If you submit a check\nwith an `externalId` that already exists for another check, the request\nwill fail. You can use this behavior to implement idempotent check\nsubmission by always providing a consistent `externalId` for each unique\ncheck attempt.\n",
      "allOf": [
        {
          "$ref": "#/$defs/ExternalReference"
        },
        {
          "type": "object",
          "required": [
            "selections"
          ],
          "properties": {
            "createdDate": {
              "description": "The date and time that the Toast platform received the check.",
              "type": "string",
              "format": "date-time"
            },
            "openedDate": {
              "description": "The date on which this check was opened. If not specified, it is set to the current system time.",
              "type": "string",
              "format": "date-time"
            },
            "closedDate": {
              "type": "string",
              "format": "date-time",
              "description": "The most recent date on which this check's payment status was set to `CLOSED`."
            },
            "modifiedDate": {
              "type": "string",
              "format": "date-time",
              "description": "The most recent date on which this check was modified."
            },
            "deletedDate": {
              "type": "string",
              "format": "date-time",
              "description": "The date on which this check was deleted.\n\n`deletedDate` is only applicable when `deleted` is true.\n\nIf `deleted` is false, then `deletedDate` is set to the UNIX epoch, `1970-01-01T00:00:00.000+0000`.\n"
            },
            "deleted": {
              "type": "boolean",
              "description": "Set to `true` if this check was deleted."
            },
            "selections": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/Selection"
              }
            },
            "customer": {
              "description": "A `Customer` object\nthat holds information about a restaurant guest\nthat is associated with the check.\n\nRequired for `POST` requests for orders that use the\ntakeout or delivery dining options.\n\nFor checks that apply or accrue Toast loyalty points, a\n`GET` request returns a `Customer` object\neven when restaurant employees do not enter guest\ninformation for a check. In this case, the `Customer` object\ncontains only the Toast platform GUID of the guest.\nAll other values are `null`.\n",
              "$ref": "#/$defs/Customer"
            },
            "appliedLoyaltyInfo": {
              "description": "Information about the customer loyalty program account associated with the check. Used to accrue loyalty program benefits and to redeem loyalty program discounts.",
              "$ref": "#/$defs/AppliedLoyaltyInfo"
            },
            "taxExempt": {
              "type": "boolean",
              "default": false,
              "description": "Set to `true` if this check is tax exempt."
            },
            "displayNumber": {
              "type": "string",
              "description": "Generally starts at one each day and counts up. The Toast platform fills this in if it is not specified when the order is POSTed. Not guaranteed to be unique."
            },
            "appliedServiceCharges": {
              "type": "array",
              "description": "Any restaurant-configured service charges that applied to this check.",
              "items": {
                "$ref": "#/$defs/AppliedServiceCharge"
              }
            },
            "amount": {
              "x-toast-read-only": true,
              "type": "number",
              "format": "double",
              "description": "The total calculated price of the check including discounts and service charges. The `amount` does not include gratuity or taxes. Response only."
            },
            "taxAmount": {
              "x-toast-read-only": true,
              "type": "number",
              "format": "double",
              "description": "The calculated tax amount. Includes service charge and item level taxes. Response only."
            },
            "totalAmount": {
              "type": "number",
              "format": "double",
              "description": "The total calculated price of this check including discounts and taxes. Not affected by refunds."
            },
            "payments": {
              "type": "array",
              "description": "Payments made on this check.",
              "minItems": 0,
              "items": {
                "$ref": "#/$defs/Payment"
              }
            },
            "tabName": {
              "type": "string",
              "description": "The name of the tab on this check. This displays on the KDS (Kitchen Display System) for pending orders.\n\nThe `tabName` value can contain up to 255 characters.\n"
            },
            "paymentStatus": {
              "x-toast-read-only": true,
              "type": "string",
              "description": "The payment status of this check.\n\nValid values:\n\n* `OPEN` - There is an outstanding balance.\n\n* `PAID` - A credit card payment was applied, but the tip has not been adjusted.\n\n* `CLOSED`  - There is no remaining amount due on this check. For credit card payments, the payment has been adjusted to reflect the tip. Toast does not prevent a `CLOSED` check from transitioning back to `OPEN` or `PAID`.\n\nResponse only.\n",
              "enum": [
                "OPEN",
                "PAID",
                "CLOSED"
              ]
            },
            "appliedDiscounts": {
              "type": "array",
              "description": "The discounts applied to this check. In a `POST` request, only one `appliedDiscount` is allowed per check.",
              "minItems": 0,
              "items": {
                "$ref": "#/$defs/AppliedDiscount"
              }
            },
            "voided": {
              "x-toast-read-only": true,
              "type": "boolean",
              "description": "True if this check is voided. Response only."
            },
            "voidDate": {
              "x-toast-read-only": true,
              "type": "string",
              "format": "date-time",
              "description": "The date when this check was voided. Response only."
            },
            "voidBusinessDate": {
              "x-toast-read-only": true,
              "type": "integer",
              "description": "The business date (yyyyMMdd) on which this check was voided. Response only."
            },
            "paidDate": {
              "type": "string",
              "format": "date-time",
              "description": "The most recent date when this check received payment. If not specified when `POST`ing, it is set to the current system time."
            },
            "createdDevice": {
              "description": "The Toast POS device that created the check. This value is `null` if the check was not created using a Toast POS device.",
              "$ref": "#/$defs/Device"
            },
            "lastModifiedDevice": {
              "description": "The Toast POS device that modified the check most recently. This value is `null` if the check was never modified using a Toast POS device.\n\nIf the check is modified but the modification was not made using a Toast POS device, then this value does not change.\n",
              "type": "object",
              "$ref": "#/$defs/Device"
            },
            "duration": {
              "x-toast-read-only": true,
              "type": "integer",
              "description": "The number of seconds between creation and payment. Response only."
            },
            "openedBy": {
              "description": "The restaurant employee, or server, who opened the check.",
              "$ref": "#/$defs/ExternalReference"
            }
          }
        }
      ],
      "name": "Check"
    },
    "DeliveryInfo": {
      "type": "object",
      "description": "Information related to delivery orders. Required if the dining option behavior is `DELIVERY`.",
      "required": [
        "address1",
        "city",
        "state",
        "zipCode"
      ],
      "properties": {
        "address1": {
          "type": "string",
          "description": "The first line of the street address of the delivery destination.\n",
          "example": "string"
        },
        "address2": {
          "type": "string",
          "description": "The second line of the street address of the delivery destination.\n",
          "example": "string"
        },
        "city": {
          "type": "string",
          "description": "The name of the city or town of the delivery destination.\n",
          "example": "string"
        },
        "administrativeArea": {
          "type": "string",
          "description": "The geographic or government division, larger than a city/town, for\nthe delivery destination. For example, the name of a province, county,\nregion, or state might be the `administrativeArea` value for a\ndelivery address. This value is optional, not all delivery addresses\ninclude a regional area name other than a `city`. If you include the \n`state` value, you would typically _not_ include an `administrativeArea`.\n",
          "example": "string"
        },
        "state": {
          "type": "string",
          "format": "ISO 3166-2",
          "description": "The postal abbreviation of the state or province of the\ndelivery destination.\n\nThe abbreviation must be in ISO 3166-2\nformat (two capital letters).\n",
          "example": "string"
        },
        "zipCode": {
          "type": "string",
          "description": "The postal or zip code of the delivery destination.\n",
          "example": "string"
        },
        "country": {
          "type": "string",
          "description": "The two-digit ISO-3166-2 country code of the delivery destination.\n",
          "example": "string"
        },
        "latitude": {
          "type": "double",
          "description": "The north/south geographic coordinate of the delivery\ndestination, in decimal format.\n",
          "example": 1.0
        },
        "longitude": {
          "type": "double",
          "description": "The east/west geographic coordinate of the delivery\ndestination, in decimal format.\n",
          "example": 1.0
        },
        "notes": {
          "description": "Additional instructions or information about the delivery.\n",
          "type": "string",
          "example": "string"
        },
        "deliveredDate": {
          "x-toast-read-only": true,
          "type": "datetime",
          "description": "The date and time that the delivery employee indicated in the Toast POS app that\nthe order was delivered. Response only.\n\nThis value is only set when the dining option for the order is\n`DELIVERY`. For other dining options, the value is `null`.\n",
          "example": "2025-02-07T08:00:00.000-0800"
        },
        "dispatchedDate": {
          "type": "datetime",
          "description": "The date and time that the restaurant indicated in the Toast POS app that the\norder was available for delivery and assigned to a delivery\nemployee.\n\nThis value is only set when the\ndining option for the order is `DELIVERY`. For other dining\noptions, the value is `null`.\n",
          "example": "2025-02-07T08:00:00.000-0800"
        },
        "deliveryEmployee": {
          "description": "The Toast GUID of the employee who delivers the order.\n",
          "type": "object",
          "$ref": "#/$defs/ExternalReference"
        },
        "deliveryState": {
          "description": "An internal representation of the state of a delivery order.\n\nValid values:\n\n* `PENDING` - The delivery is not dispatched. This corresponds to the **Unassigned** tab of\nthe Delivery screen of the Toast POS app.\n\n* `IN_PROGRESS` - The order is on the way to the destination. This corresponds to \nthe **En Route** tab of the Delivery screen of the Toast POS app.\n\n* `PICKED_UP` - The employee who delivers the order has picked up the order from the\nrestaurant.\n\n* `DELIVERED` - The order was delivered. This corresponds to the **Delivered** tab of the\nDelivery screen of the Toast POS app.\n",
          "type": "string",
          "enum": [
            "PENDING",
            "IN_PROGRESS",
            "PICKED_UP",
            "DELIVERED"
          ],
          "example": "PENDING"
        }
      },
      "name": "DeliveryInfo"
    },
    "Device": {
      "type": "object",
      "description": "The *Device ID* value that the Toast platform assigns to a specific Toast POS device.\n\nThe `id` value is a unique identifier for a device.\n\nTo find the ID for a Toast POS device, from the overflow  menu (\u22ee) select *Device Status* and then select the *Device* tab.\n",
      "properties": {
        "id": {
          "type": "string",
          "description": "The physical id of the device",
          "example": "90a86f12"
        }
      },
      "name": "Device"
    },
    "CurbsidePickupInfo": {
      "type": "object",
      "description": "Information that the restaurant can use to identify a guest when they arrive\noutside the restaurant to pick up their order. `transportDescription` is a required field.\n",
      "allOf": [
        {
          "$ref": "#/$defs/ToastReference"
        },
        {
          "type": "object",
          "properties": {
            "transportColor": {
              "description": "The color of the guest's vehicle if they will arrive at the restaurant in a vehicle to pick up their order.\n",
              "type": "string",
              "maxLength": 20
            },
            "transportDescription": {
              "description": "Information about how the guest will arrive at the restaurant to pick up their order.\n\nFor example, the make and model of the vehicle the guest will arrive in.\n",
              "type": "string",
              "maxLength": 100
            },
            "notes": {
              "description": "Extra notes.\n",
              "type": "string",
              "maxLength": 100
            }
          }
        }
      ],
      "name": "CurbsidePickupInfo"
    },
    "MarketplaceFacilitatorTaxInfo": {
      "type": "object",
      "description": "Information about the taxes that a marketplace facilitator\norganization remits on behalf of a Toast platform restaurant.\n`POST` only. The orders API does not include the\n`MarketplaceFacilitatorTaxInfo` object in response data.\n\n**Note**: you can only include this information if your\nToast API client is associated with a designated\nmarketplace facilitator organization. Most Toast API\nclients do not create marketplace facilitator orders.\n",
      "properties": {
        "facilitatorCollectAndRemitTaxOrder": {
          "description": "Indicates whether a marketplace facilitator organization has\npaid the tax amounts for an order on behalf of the restaurant\nthat fulfills the order.\n\nIf you include this value, you indicate that the marketplace\nfacilitator order uses the prices and tax amounts calculated\nby the Toast platform.\n\nIf you include this value, you *must not* include the `taxes`\nvalue and you *must not* include the `externalPriceAmount`\nfor menu item selections in the order.\n",
          "type": "boolean",
          "example": true
        },
        "taxes": {
          "description": "An array of `AppliedTaxRate` objects that describe the tax\namounts that apply to a marketplace facilitator order.\n\nIf you include this value, you must include an `externalPriceAmount`\nfor each menu item selection in the order.\n",
          "type": "array",
          "items": {
            "$ref": "#/$defs/AppliedTaxRate"
          }
        }
      },
      "name": "MarketplaceFacilitatorTaxInfo"
    },
    "AppliedTaxRate": {
      "type": "object",
      "description": "A tax rate that is applied to an item or service charge.",
      "required": [
        "taxRate"
      ],
      "allOf": [
        {
          "$ref": "#/$defs/ToastReference"
        },
        {
          "type": "object",
          "properties": {
            "entityType": {
              "description": "The type of object this is.",
              "type": "string"
            },
            "taxRate": {
              "type": "object",
              "$ref": "#/$defs/ToastReference"
            },
            "name": {
              "type": "string",
              "description": "The name of the tax rate."
            },
            "rate": {
              "type": "number",
              "format": "double",
              "description": "The tax rate, which can be a fixed amount, a percentage, or null."
            },
            "taxAmount": {
              "type": "number",
              "format": "double",
              "description": "The tax amount that was actually applied."
            },
            "type": {
              "type": "string",
              "description": "The type of the tax rate. Default is `PERCENT`.\n\nThe value `EXTERNAL` indicates that the tax is for a marketplace\nfacilitator order, and that the marketplace facilitator\norganization calculated the tax amount.\n",
              "enum": [
                "PERCENT",
                "FIXED",
                "NONE",
                "TABLE",
                "EXTERNAL"
              ]
            },
            "facilitatorCollectAndRemitTax": {
              "type": "boolean",
              "description": "Indicates whether the marketplace facilitator that\nreceived a guest order remitted the tax amount on behalf\nof the Toast platform restaurant.\n\nYou can use this information to identify tax amounts that\nhave already been paid by an ordering service provider\nand do not need to be paid again.\n\n* `true` - The marketplace facilitator paid the tax\namount on behalf of the Toast platform restaurant\nlocation.\n\n* `false` - The marketplace facilitator has not paid the\ntax amount. The Toast platform restaurant location may be\nrequired to pay the tax amount.\n\n**Note**: Toast API response data is not guidance or\nadvice for tax compliance.\n"
            },
            "displayName": {
              "type": "string",
              "description": "The name of the tax rate as it appears on guest receipts."
            },
            "jurisdiction": {
              "type": "string",
              "description": "The state or province of the tax rate for reporting purposes."
            },
            "jurisdictionType": {
              "type": "string",
              "description": "The jurisdiction type (ex. STATE, COUNTY, etc.) of the tax rate for reporting purposes."
            }
          }
        }
      ],
      "name": "AppliedTaxRate"
    },
    "AppliedPackagingInfo": {
      "type": "object",
      "description": "Information describing the guest's packaging preferences for this order, for example utensils, napkins, condiments.\n\nFor more information, see [Packaging preferences](https://doc.toasttab.com/doc/devguide/apiOrdersPackagingPreferences.html)\n",
      "allOf": [
        {
          "$ref": "#/$defs/ToastReference"
        },
        {
          "type": "object",
          "properties": {
            "appliedPackagingItems": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/$defs/AppliedPackagingItem"
              }
            }
          }
        }
      ],
      "name": "AppliedPackagingInfo"
    }
  }
}