{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/toast-tab/refs/heads/main/json-schema/orders-selection-schema.json", "title": "Selection", "description": "A `Selection` object can represent either a primary item (for example,\n`Check.selections`) or a modifier (`Selection.modifiers`) selection.\nQuantity defaults to `1`.\n\nFor a `POST` operation, all selections must have valid `item` and\n`itemGroup` fields. The `item` and `itemGroup` values can be `null` for\n`GET` requests. For example, they are `null` for gift cards and on special\nrequests.\n\nTo specify a modifier selection, add it to the `modifiers` list of\nanother selection. Each modifier selection must have its `optionGroup` field\nset correctly, because a `MenuItem` can be included in multiple\n`MenuOptionGroups`, potentially with different prices or sizing.\n\nThe `externalId` value for a selection must be unique. If you submit a\nselection with an `externalId` that already exists for another selection,\nthe request will fail. You can use this behavior to implement idempotent\nselection submission by always providing a consistent `externalId` for\neach unique selection attempt.\n", "type": "object", "allOf": [ { "$ref": "#/$defs/ExternalReference" }, { "type": "object", "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "description": "A reference to the selected menu item.", "$ref": "#/$defs/ConfigReference" }, "itemGroup": { "type": "object", "description": "A reference to the menu group from which the item was selected.", "$ref": "#/$defs/ConfigReference" }, "optionGroup": { "type": "object", "description": "A reference to the modifier group from which the menu item was selected. Only applies if this is a modifier selection.", "$ref": "#/$defs/ConfigReference" }, "preModifier": { "type": "object", "description": "A reference to the selected pre-modifier.", "$ref": "#/$defs/ConfigReference" }, "quantity": { "type": "number", "format": "double", "description": "Quantity ordered. For items sold by weight, a decimal number. For discrete items, a counting number." }, "seatNumber": { "x-toast-read-only": true, "type": "integer", "description": "Indicates which guest seat at a restaurant table ordered\na menu item selection. Restaurant employees can choose the\nseat number when they add a menu item to a guest check.\n\n* A positive integer value indicates the seat number for\n the menu item.\n\n* `0` - Indicates that the menu item is shared by\n multiple guests.\n\n* `-1` - Indicates that the restaurant employee did not\n select a seat for the menu item.\n\nResponse only.\n" }, "unitOfMeasure": { "type": "string", "description": "The unit of measure used to weigh, determine size, or otherwise\nquantify the item.\n\nThe default is `NONE`, which means that the item is not meant to\nbe measured during a sale.\n\nValues are:\n* `NONE` - The item is not meant to be measured.\n* `LB` - Weighed in pounds.\n* `OZ` - Weighed in ounces.\n* `KG` - Weighed in kilograms.\n* `G` - Weighed in grams.\n* `GAL` - Measured in gallons.\n* `L` - Measured in liters.\n* `ML` - Measured in milliliters.\n* `FL_OZ` - Measured in fluid ounces.\n* `M` - Measured in meters.\n* `CM` - Measured in centimeters.\n* `FT` - Measured in feet.\n* `IN` - Measured in inches.\n* `YD` - Measured in yards.\n", "enum": [ "NONE", "LB", "OZ", "KG", "G", "GAL", "L", "ML", "FL_OZ", "M", "CM", "FT", "IN", "YD" ] }, "selectionType": { "type": "string", "description": "Specifies whether this selection is a special request or other off-menu sale.\n\nIf `null` or `NONE`, describes a normal modifier or item selection.\n\n`TOAST_CARD_SELL` and `TOAST_CARD_RELOAD` are currently response-only.\n", "enum": [ "NONE", "OPEN_ITEM", "SPECIAL_REQUEST", "PORTION", "HOUSE_ACCOUNT_PAY_BALANCE", "TOAST_CARD_SELL", "TOAST_CARD_RELOAD" ] }, "salesCategory": { "x-toast-read-only": true, "type": "object", "description": "A reference to the sales category of the item. Response only.", "$ref": "#/$defs/ConfigReference" }, "appliedDiscounts": { "x-toast-read-only": true, "type": "array", "description": "The itemized discounts that are applied to this item. Response only.", "minItems": 0, "items": { "$ref": "#/$defs/AppliedDiscount" } }, "deferred": { "type": "boolean", "description": "Whether this selection is a deferred revenue transaction, such as a gift card sale." }, "preDiscountPrice": { "x-toast-read-only": true, "type": "number", "description": "Gross sale price for this selection. Excludes tax. Response only.", "format": "double" }, "price": { "x-toast-read-only": true, "type": "number", "format": "double", "description": "Net price for this selection. The final price of the item after considering discounts (including discounts at the check level), quantity adjustments, and modifier prices at the time the item was selected for purchase. Response only." }, "tax": { "x-toast-read-only": true, "type": "number", "format": "double", "description": "The total tax amount for this selection. Response only." }, "voided": { "x-toast-read-only": true, "type": "boolean", "description": "Set to `true` if this selection is voided. Response only." }, "voidDate": { "x-toast-read-only": true, "type": "string", "format": "date-time", "description": "The date on which this selection was voided. Response only." }, "voidBusinessDate": { "x-toast-read-only": true, "type": "integer", "description": "The business date (yyyyMMdd) on which this selection was voided. Response only." }, "voidReason": { "x-toast-read-only": true, "type": "object", "description": "If `voided` is `true`, a reference to the void reason. Response only.", "$ref": "#/$defs/ExternalReference" }, "refundDetails": { "description": "A `RefundDetails` object that\ncontains information about refunded payment amounts for the item.\n", "type": "object", "$ref": "#/$defs/RefundDetails" }, "displayName": { "type": "string", "description": "The display name of the selection.\n\nCan be used to set a special request value.\n\nOtherwise, it is generated from this selection's item property.\n" }, "plu": { "x-toast-read-only": true, "type": "string", "description": "The price look-up (PLU) code for the menu item selection used for pricing and inventory management." }, "premodifierPlu": { "x-toast-read-only": true, "type": "string", "description": "The Price Look-Up (PLU) code for the premodifier associated with this menu item selection. This is a unique identifier used for pricing and inventory management purposes. Currently this field is read only." }, "createdDate": { "type": "string", "format": "date-time", "description": "The date on which this selection was created. If not specified, defaults to the current time." }, "modifiedDate": { "type": "string", "format": "date-time", "description": "The date on which this selection was last modified. If not specified, defaults to the current time." }, "modifiers": { "type": "array", "description": "A list of modifiers that apply to this selection.", "items": { "$ref": "#/$defs/Selection" } }, "fulfillmentStatus": { "x-toast-read-only": true, "type": "string", "default": "NEW", "description": "Indicates the stage of the preparation workflow that the\nmenu item selection is in.\n\nThe `fulfillmentStatus` of a\nmenu item selection changes as restaurant employees move\nthe item through the functions of the Toast POS, for\nexample order entry and the kitchen display system (KDS).\nResponse only.\n\nValid values:\n\n* `NEW` - The menu item selection was added to a\n check but is not yet sent to the KDS for\n preparation.\n\n* `HOLD` - A restaurant employee paused the menu\n item selection so that it does not appear in the\n KDS for preparation.\n\n* `SENT` - The menu item selection was fired and\n appears in the KDS for preparation.\n\n* `READY` - Preparation is complete. The menu item\n selection is fulfilled and no longer appears in\n the KDS. If your restaurant does not use the Toast platform\n KDS, then order items do not reach the `READY`\n status.\n", "enum": [ "NEW", "HOLD", "SENT", "READY" ] }, "fulfillment": { "x-toast-read-only": true, "type": "object", "description": "Information about the fulfillment requirements for this menu item selection. Response only.\n", "$ref": "#/$defs/Fulfillment" }, "taxInclusion": { "type": "string", "description": "Indicates whether the menu item price includes one or more tax\namounts. If the menu item is a modifier for another menu item\nselection, it always inherits the tax inclusion behavior of the menu\nitem that it applies to.\n\nValid values:\n* `INCLUDED` - The menu item price includes one or more tax amounts.\n* `NOT_INCLUDED` - The menu item price does not include any tax\n amounts.\n* `INHERITED` - The menu item is a modifier for another menu item\n selection in the check. The `taxInclusion` value of the parent menu\n item selection applies to the modifier. If a menu item selection\n *that is not a modifier* inherits tax inclusion behavior from a\n menu or menu group, the `taxInclusion` value is either\n `INCLUDED` or `NOT_INCLUDED`.\n", "enum": [ "INCLUDED", "NOT_INCLUDED", "INHERITED" ] }, "appliedTaxes": { "x-toast-read-only": true, "type": "array", "description": "An array of `AppliedTaxRate` objects that contain information about tax payments made for the selection. Response only.", "items": { "$ref": "#/$defs/AppliedTaxRate" } }, "diningOption": { "x-toast-read-only": true, "description": "A reference to the setting or method that a restaurant uses to fulfill orders. For example, dine-in, takeout, or delivery might be dining options.\n\nRestaurants configure the dining options that they fulfill orders in.\n\nResponse only.\n", "type": "object", "$ref": "#/$defs/ExternalReference" }, "openPriceAmount": { "description": "A non-negative currency amount that sets the price of a\nmenu item that is configured to use the *Open Price*\npricing strategy. If you do not supply an\n`openPriceAmount` value for an open price menu item, the\norders API sets the price to 0.00.\n\nIf a menu item is configured to use tax-inclusive\npricing, the orders API calculates the base price and tax\namount based on the open price that you specify. _The\nopen-price amount includes both the base-price and\ninclusive tax amount._\n\n`POST` only. The `openPriceAmount` value is not\npresent in orders API return data. It is used to\npopulate `receiptLinePrice`.\n", "type": "number", "format": "double" }, "receiptLinePrice": { "type": "number", "format": "double", "description": "The price of the menu item selection without any quantity, taxes, \ndiscounts, and modifier adjustments. If the menu item has taxes included, the `receiptLinePrice` value shows the original price, including taxes.\n\nFor example, if the menu item selection is for two orders of fries, \n`receiptLinePrice` is the price of one order of fries. If a menu item selection \nis for three large drinks, receiptLinePrice is the price of one large drink.\n\nPopulated based on the menu configuration, or using the value provided in \n`externalPriceAmount` or `openPriceAmount`.\n" }, "optionGroupPricingMode": { "type": "string", "description": "Information about how the modifier group affects the pricing of its parent item.", "enum": [ "INCLUDED", "FIXED_PRICE", "ADJUSTS_PRICE", "REPLACES_PRICE", "LOCATION_SPECIFIC_PRICE" ] }, "externalPriceAmount": { "description": "The menu item price that was calculated by the\nmarketplace facilitator organization that created the\norder.\n\n`POST` only. The orders API does not include the\n`externalPriceAmount` value in return data. It is\nused to populate `receiptLinePrice`.\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", "type": "number", "format": "double" }, "splitOrigin": { "description": "Reserved for future use.\n", "type": "object", "$ref": "#/$defs/ExternalReference" } } } ], "$defs": { "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" } } } ] }, "ConfigReference": { "type": "object", "description": "A wrapper object containing identifier values for Toast platform entities.\n", "allOf": [ { "$ref": "#/$defs/ToastReference" }, { "type": "object", "properties": { "multiLocationId": { "description": "A consistent identifier for Toast platform entities, such\nas menu items, that applies to all versions of a shared\nentity at all locations in a restaurant group.\n\nFor example, you can use the `multiLocationId` value to\nidentify menu entities that are versions of a shared menu\nentity. For more information about the menus API `multilocationId` value, see\n[the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiUnderstandingGuidsEntityIdentifiersAndMultilocationIds_V2.html#apiMultilocationIdValues_V2).\n", "type": "string" }, "externalId": { "description": "An external identifier that is prefixed by a naming\nauthority. Deprecated for use in `ConfigReference`.\n", "type": "string" } } } ] }, "AppliedDiscount": { "type": "object", "description": "A discount applied to a check or item. The Toast platform calculates service\ncharges before it applies discounts. The system calculates tax after applying\ndiscounts.\n\nIn a `POST` request, you cannot apply open percent discounts. You can apply open amount discounts.\nYou can only apply one discount to a menu item selection. For more information, see\n[the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiDiscountingOrders.html).\n", "allOf": [ { "$ref": "#/$defs/ExternalReference" }, { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the applied discount." }, "discountAmount": { "type": "number", "format": "double", "description": "The discount amount. This amount is subtracted from the check or item." }, "nonTaxDiscountAmount": { "type": "number", "format": "double", "description": "The amount that a discount reduces a menu item price,\nexcluding any discount amount applied to taxes.\n\nIn most cases, a discount only applies to the menu item price, and\nthe `nonTaxDiscountAmount` is the same as the `discountAmount`.\n\nIf you apply a discount to a menu item that includes tax in\nits price, the `nonTaxDiscountAmount` is less than `discountAmount`.\n" }, "discount": { "type": "object", "description": "A GUID reference to the discount configured for the restaurant.", "$ref": "#/$defs/ToastReference" }, "triggers": { "x-toast-read-only": true, "type": "array", "description": "Optional items that triggered this discount. Response only.", "items": { "$ref": "#/$defs/AppliedDiscountTrigger" } }, "approver": { "x-toast-read-only": true, "type": "object", "description": "The user who approved the discount. Response only.", "$ref": "#/$defs/ExternalReference" }, "processingState": { "x-toast-read-only": true, "readOnly": true, "type": "string", "description": "Applies to loyalty program discounts only. Loyalty\nprogram reward discounts are validated and then applied,\nor redeemed, by the third-party loyalty program service\nprovider depending on the state of the Toast platform order.\n\nThis field's value is `null` if the order discount is a Toast discount.\n\nThis value indicates the state of the discount in that\nvalidation and application process. Response only.\n\nValid values:\n\n* `PENDING_APPLIED` - The loyalty program\n service provider confirmed that the reward discount\n is valid for the order and customer. The reward is not yet\n redeemed, or applied to the customer's loyalty\n account.\n* `APPLIED` - The reward discount is\n redeemed. The reward is no longer available from the\n customer's loyalty program account.\n* `PENDING_VOID` - The reward discount was\n removed from the Toast platform order. The reward is not\n available from the customer's loyalty program account\n until the loyalty program service provider processes\n the void operation.\n* `VOID` - The reward discount was removed\n from the Toast platform order and the reward is available from\n the customer's loyalty program account again.\n", "enum": [ "PENDING_APPLIED", "APPLIED", "PENDING_VOID", "VOID" ] }, "appliedDiscountReason": { "x-toast-read-only": true, "type": "object", "description": "An optional reason for the applied discount. Response only.", "$ref": "#/$defs/AppliedDiscountReason" }, "loyaltyDetails": { "type": "object", "description": "Information about the customer loyalty program discount that is being applied to the check.", "$ref": "#/$defs/LoyaltyDetails" }, "comboItems": { "x-toast-read-only": true, "type": "array", "description": "A list of menu item selections that this combo discount applies to. Empty for non-combo discounts. Response only.", "items": { "$ref": "#/$defs/ExternalReference" } }, "appliedPromoCode": { "type": "string", "description": "The promo code that was applied for this discount.\n\nFor a POSTed order, the Toast platform cannot validate the promo code.\n" }, "discountType": { "type": "string", "description": "The behavior of this discount.\n\nValid values:\n* `BOGO` - Buy One, Get One. The guest receives a discount based on purchasing a specific item or items.\n* `PERCENT` - The guest receives a specific percentage off of the price.\n* `FIXED` - The guest receives a fixed currency amount off of the price.\n* `OPEN_PERCENT` - The guest receives a percentage off of the price. The percentage is specified when the order is placed.\n* `OPEN_FIXED` - The guest receives a currency amount off of the price. The amount is specified when the order is placed.\n* `FIXED_TOTAL` - The guest pays a specified discounted price when they purchase specific items. Also referred to as a combo discount.\n", "enum": [ "BOGO", "PERCENT", "FIXED", "OPEN_PERCENT", "OPEN_FIXED", "FIXED_TOTAL" ] }, "discountPercent": { "type": "number", "format": "double", "description": "The percent value (0-100) of the applied discount when the `discountType` is `PERCENT` or `OPEN_PERCENT`. For other discount types, this value is `null`." } } } ] }, "RefundDetails": { "type": "object", "description": "Information about refunded currency amounts for an item\nselection, modifier option, or service charge. The refund\ninformation includes separate values for the pre-tax value\nbeing refunded and the tax amount being refunded.\n", "properties": { "refundAmount": { "description": "The value of the menu item or service charge (excluding taxes) being\nrefunded. Includes the value of any nested modifier options that\nincreased the price of the item or modifier option (an upcharge for\nthe modifier option).\n", "type": "number", "format": "double", "example": 1.0 }, "taxRefundAmount": { "description": "The tax amount being refunded.\n", "type": "number", "format": "double", "example": 1.0 }, "refundTransaction": { "description": "An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.\n", "type": "object", "$ref": "#/$defs/RefundTransaction" } } }, "RefundTransaction": { "allOf": [ { "$ref": "#/$defs/ToastReference" }, { "type": "object", "description": "An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.\n" } ] }, "Selection": { "type": "object", "description": "A `Selection` object can represent either a primary item (for example,\n`Check.selections`) or a modifier (`Selection.modifiers`) selection.\nQuantity defaults to `1`.\n\nFor a `POST` operation, all selections must have valid `item` and\n`itemGroup` fields. The `item` and `itemGroup` values can be `null` for\n`GET` requests. For example, they are `null` for gift cards and on special\nrequests.\n\nTo specify a modifier selection, add it to the `modifiers` list of\nanother selection. Each modifier selection must have its `optionGroup` field\nset correctly, because a `MenuItem` can be included in multiple\n`MenuOptionGroups`, potentially with different prices or sizing.\n\nThe `externalId` value for a selection must be unique. If you submit a\nselection with an `externalId` that already exists for another selection,\nthe request will fail. You can use this behavior to implement idempotent\nselection submission by always providing a consistent `externalId` for\neach unique selection attempt.\n", "allOf": [ { "$ref": "#/$defs/ExternalReference" }, { "type": "object", "required": [ "item", "quantity" ], "properties": { "item": { "type": "object", "description": "A reference to the selected menu item.", "$ref": "#/$defs/ConfigReference" }, "itemGroup": { "type": "object", "description": "A reference to the menu group from which the item was selected.", "$ref": "#/$defs/ConfigReference" }, "optionGroup": { "type": "object", "description": "A reference to the modifier group from which the menu item was selected. Only applies if this is a modifier selection.", "$ref": "#/$defs/ConfigReference" }, "preModifier": { "type": "object", "description": "A reference to the selected pre-modifier.", "$ref": "#/$defs/ConfigReference" }, "quantity": { "type": "number", "format": "double", "description": "Quantity ordered. For items sold by weight, a decimal number. For discrete items, a counting number." }, "seatNumber": { "x-toast-read-only": true, "type": "integer", "description": "Indicates which guest seat at a restaurant table ordered\na menu item selection. Restaurant employees can choose the\nseat number when they add a menu item to a guest check.\n\n* A positive integer value indicates the seat number for\n the menu item.\n\n* `0` - Indicates that the menu item is shared by\n multiple guests.\n\n* `-1` - Indicates that the restaurant employee did not\n select a seat for the menu item.\n\nResponse only.\n" }, "unitOfMeasure": { "type": "string", "description": "The unit of measure used to weigh, determine size, or otherwise\nquantify the item.\n\nThe default is `NONE`, which means that the item is not meant to\nbe measured during a sale.\n\nValues are:\n* `NONE` - The item is not meant to be measured.\n* `LB` - Weighed in pounds.\n* `OZ` - Weighed in ounces.\n* `KG` - Weighed in kilograms.\n* `G` - Weighed in grams.\n* `GAL` - Measured in gallons.\n* `L` - Measured in liters.\n* `ML` - Measured in milliliters.\n* `FL_OZ` - Measured in fluid ounces.\n* `M` - Measured in meters.\n* `CM` - Measured in centimeters.\n* `FT` - Measured in feet.\n* `IN` - Measured in inches.\n* `YD` - Measured in yards.\n", "enum": [ "NONE", "LB", "OZ", "KG", "G", "GAL", "L", "ML", "FL_OZ", "M", "CM", "FT", "IN", "YD" ] }, "selectionType": { "type": "string", "description": "Specifies whether this selection is a special request or other off-menu sale.\n\nIf `null` or `NONE`, describes a normal modifier or item selection.\n\n`TOAST_CARD_SELL` and `TOAST_CARD_RELOAD` are currently response-only.\n", "enum": [ "NONE", "OPEN_ITEM", "SPECIAL_REQUEST", "PORTION", "HOUSE_ACCOUNT_PAY_BALANCE", "TOAST_CARD_SELL", "TOAST_CARD_RELOAD" ] }, "salesCategory": { "x-toast-read-only": true, "type": "object", "description": "A reference to the sales category of the item. Response only.", "$ref": "#/$defs/ConfigReference" }, "appliedDiscounts": { "x-toast-read-only": true, "type": "array", "description": "The itemized discounts that are applied to this item. Response only.", "minItems": 0, "items": { "$ref": "#/$defs/AppliedDiscount" } }, "deferred": { "type": "boolean", "description": "Whether this selection is a deferred revenue transaction, such as a gift card sale." }, "preDiscountPrice": { "x-toast-read-only": true, "type": "number", "description": "Gross sale price for this selection. Excludes tax. Response only.", "format": "double" }, "price": { "x-toast-read-only": true, "type": "number", "format": "double", "description": "Net price for this selection. The final price of the item after considering discounts (including discounts at the check level), quantity adjustments, and modifier prices at the time the item was selected for purchase. Response only." }, "tax": { "x-toast-read-only": true, "type": "number", "format": "double", "description": "The total tax amount for this selection. Response only." }, "voided": { "x-toast-read-only": true, "type": "boolean", "description": "Set to `true` if this selection is voided. Response only." }, "voidDate": { "x-toast-read-only": true, "type": "string", "format": "date-time", "description": "The date on which this selection was voided. Response only." }, "voidBusinessDate": { "x-toast-read-only": true, "type": "integer", "description": "The business date (yyyyMMdd) on which this selection was voided. Response only." }, "voidReason": { "x-toast-read-only": true, "type": "object", "description": "If `voided` is `true`, a reference to the void reason. Response only.", "$ref": "#/$defs/ExternalReference" }, "refundDetails": { "description": "A `RefundDetails` object that\ncontains information about refunded payment amounts for the item.\n", "type": "object", "$ref": "#/$defs/RefundDetails" }, "displayName": { "type": "string", "description": "The display name of the selection.\n\nCan be used to set a special request value.\n\nOtherwise, it is generated from this selection's item property.\n" }, "plu": { "x-toast-read-only": true, "type": "string", "description": "The price look-up (PLU) code for the menu item selection used for pricing and inventory management." }, "premodifierPlu": { "x-toast-read-only": true, "type": "string", "description": "The Price Look-Up (PLU) code for the premodifier associated with this menu item selection. This is a unique identifier used for pricing and inventory management purposes. Currently this field is read only." }, "createdDate": { "type": "string", "format": "date-time", "description": "The date on which this selection was created. If not specified, defaults to the current time." }, "modifiedDate": { "type": "string", "format": "date-time", "description": "The date on which this selection was last modified. If not specified, defaults to the current time." }, "modifiers": { "type": "array", "description": "A list of modifiers that apply to this selection.", "items": { "$ref": "#/$defs/Selection" } }, "fulfillmentStatus": { "x-toast-read-only": true, "type": "string", "default": "NEW", "description": "Indicates the stage of the preparation workflow that the\nmenu item selection is in.\n\nThe `fulfillmentStatus` of a\nmenu item selection changes as restaurant employees move\nthe item through the functions of the Toast POS, for\nexample order entry and the kitchen display system (KDS).\nResponse only.\n\nValid values:\n\n* `NEW` - The menu item selection was added to a\n check but is not yet sent to the KDS for\n preparation.\n\n* `HOLD` - A restaurant employee paused the menu\n item selection so that it does not appear in the\n KDS for preparation.\n\n* `SENT` - The menu item selection was fired and\n appears in the KDS for preparation.\n\n* `READY` - Preparation is complete. The menu item\n selection is fulfilled and no longer appears in\n the KDS. If your restaurant does not use the Toast platform\n KDS, then order items do not reach the `READY`\n status.\n", "enum": [ "NEW", "HOLD", "SENT", "READY" ] }, "fulfillment": { "x-toast-read-only": true, "type": "object", "description": "Information about the fulfillment requirements for this menu item selection. Response only.\n", "$ref": "#/$defs/Fulfillment" }, "taxInclusion": { "type": "string", "description": "Indicates whether the menu item price includes one or more tax\namounts. If the menu item is a modifier for another menu item\nselection, it always inherits the tax inclusion behavior of the menu\nitem that it applies to.\n\nValid values:\n* `INCLUDED` - The menu item price includes one or more tax amounts.\n* `NOT_INCLUDED` - The menu item price does not include any tax\n amounts.\n* `INHERITED` - The menu item is a modifier for another menu item\n selection in the check. The `taxInclusion` value of the parent menu\n item selection applies to the modifier. If a menu item selection\n *that is not a modifier* inherits tax inclusion behavior from a\n menu or menu group, the `taxInclusion` value is either\n `INCLUDED` or `NOT_INCLUDED`.\n", "enum": [ "INCLUDED", "NOT_INCLUDED", "INHERITED" ] }, "appliedTaxes": { "x-toast-read-only": true, "type": "array", "description": "An array of `AppliedTaxRate` objects that contain information about tax payments made for the selection. Response only.", "items": { "$ref": "#/$defs/AppliedTaxRate" } }, "diningOption": { "x-toast-read-only": true, "description": "A reference to the setting or method that a restaurant uses to fulfill orders. For example, dine-in, takeout, or delivery might be dining options.\n\nRestaurants configure the dining options that they fulfill orders in.\n\nResponse only.\n", "type": "object", "$ref": "#/$defs/ExternalReference" }, "openPriceAmount": { "description": "A non-negative currency amount that sets the price of a\nmenu item that is configured to use the *Open Price*\npricing strategy. If you do not supply an\n`openPriceAmount` value for an open price menu item, the\norders API sets the price to 0.00.\n\nIf a menu item is configured to use tax-inclusive\npricing, the orders API calculates the base price and tax\namount based on the open price that you specify. _The\nopen-price amount includes both the base-price and\ninclusive tax amount._\n\n`POST` only. The `openPriceAmount` value is not\npresent in orders API return data. It is used to\npopulate `receiptLinePrice`.\n", "type": "number", "format": "double" }, "receiptLinePrice": { "type": "number", "format": "double", "description": "The price of the menu item selection without any quantity, taxes, \ndiscounts, and modifier adjustments. If the menu item has taxes included, the `receiptLinePrice` value shows the original price, including taxes.\n\nFor example, if the menu item selection is for two orders of fries, \n`receiptLinePrice` is the price of one order of fries. If a menu item selection \nis for three large drinks, receiptLinePrice is the price of one large drink.\n\nPopulated based on the menu configuration, or using the value provided in \n`externalPriceAmount` or `openPriceAmount`.\n" }, "optionGroupPricingMode": { "type": "string", "description": "Information about how the modifier group affects the pricing of its parent item.", "enum": [ "INCLUDED", "FIXED_PRICE", "ADJUSTS_PRICE", "REPLACES_PRICE", "LOCATION_SPECIFIC_PRICE" ] }, "externalPriceAmount": { "description": "The menu item price that was calculated by the\nmarketplace facilitator organization that created the\norder.\n\n`POST` only. The orders API does not include the\n`externalPriceAmount` value in return data. It is\nused to populate `receiptLinePrice`.\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", "type": "number", "format": "double" }, "splitOrigin": { "description": "Reserved for future use.\n", "type": "object", "$ref": "#/$defs/ExternalReference" } } } ] }, "Fulfillment": { "type": "object", "description": "Information about the fulfillment requirements for a menu item selection.\n", "properties": { "quantity": { "type": "number", "format": "double", "description": "The quantity required for fulfillment.", "example": 1.0 }, "unit": { "type": "string", "description": "The unit of measure for the fulfillment quantity.", "example": "string" } } }, "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." } } } ] } } }