Create, Submit, and Modify Online Orders with Online Ordering
This topics linked below describe how to create, alter, and submit orders using the Online Ordering platform:
Ordering - Place a basic order using the Online Ordering API. Includes the Online Ordering Operation Definitions.
Order Object - This topic provides a detailed breakdown of the order object and all information it can contain.
Combination Meals - Create products composed of multiple child items.
Order Modifications - Create special orders, apply discounts, and change payment methods on existing orders. This includes Marketplace Facilitator Taxes.
Modifier Builds - Save a specific selection of modifiers to shorten order taking time.
Order Segments - Divide orders into segments to divide the order between multiple customers.
Pricing - Manage the prices of the items within an order.
Comment Items - Include customer comments with an order or item to provide the kitchen with individualized instructions.
Error Responses - Definitions for the possible error responses returned by the Online Ordering platform.
Child Item Sorting - Select how child items are displayed for online ordering.
Expo Numbers - Enable Expo numbers for injected orders.
Placing an Order and Online Ordering Operations
This topic describes how to use the Online Ordering API to place a basic order.
Before submitting any requests to the Online Ordering API, obtain the correct authentication tokens and identify the correct header values to include with the request.
Follow the steps to place an order:
Create an order - Send a POST request to the
/api/orderendpoint to generate a new order object with a unique ID.Add a customer to the order - Send a PUT request to the
/api/order/{_id}/customerendpoint with customer details in the request body to identify the person placing the order.Add items to the order - Send a PUT request to the
/api/order/{_id}/itemendpoint with an array of items in the request body to define the menu items that are being ordered.Add a payment method to the order - Send a PUT request to the
/api/order/{_id}/paymentwith payment details in the request body to define how the customer will pay for the order.Commit the order - Send a PUT request to the
/api/order/{_id}/commitendpoint to confirm that the order is complete and ready to be prepared.Check in the order - Send a PUT request to the
/api/order/{_id}/checkinendpoint to send the order to the store to be fulfilled.
The Online Ordering API also includes the following operations that are not directly involved in the create order process:
Get Site Status - Send a GET request to the
/api/site/statusendpoint to receive a status report on a company's sites.Create Refund Order - Send a POST request to create a refund order request using the Create Refund Order request body.
Add Refund Order Payment - Send a PUT request to add a refund order payment.
Create a new discount order - Send a PUT request to create a discount order with loyalty information.
The Online Ordering operation definitions linked in the steps above provide more details about the specific requests.
Combination Meals
Combination meals, also known as bundles, are a single product that combine multiple child items. For example, a burger meal could include a sandwich, fries, and a drink. An account manager can help define combination meal items and any acceptable variations. Users should create their online menu in a way that relates the product_id values for the included items with the product_id of the combo meal items.
To add a combo meal to an order, use the Add Items method and send the product_id values of the included items as child items.
Combination meals can also contain other combination meals within them, with up to two levels of nesting supported before the child items of a combo are excluded from the order. See the Bundles and Bundle Components topic for additional information.
Child Item Quantities
Depending on the structure of a menu, combination meals may come with more than one of a child item. For example, a breakfast sandwich combo might include two hash browns. If each hashbrown comes with two packets of ketchup, a single breakfast sandwich combo should include four packets of ketchup.
Online Ordering follows this pattern for all child item quantities. Therefore, if a customer orders two breakfast sandwich combos, the order will include four hashbrowns and eight packets of ketchup. The example below shows an items array for two of product 5507. Product 5507 is a combo item that includes one product 3502. One unit of product 3502 includes two units or product 7202. Therefore, an order for two units of product 5507 should include four units of product 7202.
The example below illustrates how to define an order for a combo items that include multiple child items:
Combo Item with Multiple Child Items
{
"store_number": "999",
"terminal": {
"id": "9"
},
"items": [
{
"product_id": "5507",
"quantity": 2,
"unit_price": 6.4,
"child_items": [
{
"product_id": "3502",
"quantity": 2,
"unit_price": 1.89,
"child_items": [
{
"product_id": "7202",
"quantity": 4,
"unit_price": 0,
"child_items": []
}
]
},
{
"product_id": "9006",
"quantity": 2,
"unit_price": 0,
"child_items": []
}
]
}
],
"customer": {
"id": "9999999999999999",
"first_name": "999999999999",
"last_name": "999999999999",
"phone_cell": "(999) 999-9999"
},
"destination": {
"id": "8"
},
"reference_id": "9999999999999999",
"order_source_id": "5"
}The next topic provides example request and response messages for adding combos to an order.
Combination Meals Add Item Example
The body of the Add Item request for a combo meal is shown below. The "product_id": "130392" is the combo meal item. The child items are the sandwich, side, and drink items that are included with the combo meal:
{
"items": [{
"product_id": "130392",
"quantity": 1,
"child_items": [{
"product_id": "130347",
"quantity": 1
}, {
"product_id": "130339",
"quantity": 1
}, {
"product_id": "130128",
"quantity": 1
}]
}]
}Send the body message shown above as a PUT request to the Add Items endpoint to return an order object with the combo meal items included and the prices calculated accordingly:
{
"order": {
"items": [
{
"item_type": "standard",
"price": 0,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130392",
"name": "WB-ML",
"time": {
"added": "20YY-04-04T17:19:01.556Z",
"last_modified": "20YY-04-04T17:19:01.718Z"
},
"unit_price": 0,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": [
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.28,
"amount_unrounded": 0.27706,
"visible": false
}
],
"total_unrounded": 0.27706,
"total": 0.28
},
"item_type": "standard",
"price": 3.64,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130347",
"name": "WB",
"time": {
"added": "20YY-04-04T17:19:01Z",
"last_modified": "20YY-04-04T17:19:01.718Z"
},
"unit_price": 3.64,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
},
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.15,
"amount_unrounded": 0.15147,
"visible": false
}
],
"total_unrounded": 0.15147,
"total": 0.15
},
"item_type": "standard",
"price": 1.99,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130339",
"name": "M-FRIES",
"time": {
"added": "20YY-04-04T17:19:01Z",
"last_modified": "20YY-04-04T17:19:01.718Z"
},
"unit_price": 1.99,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
},
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.15,
"amount_unrounded": 0.15147,
"visible": false
}
],
"total_unrounded": 0.15147,
"total": 0.15
},
"item_type": "standard",
"price": 1.99,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130128",
"name": "M-DRINK",
"time": {
"added": "20YY-04-04T17:19:01Z",
"last_modified": "20YY-04-04T17:19:01.718Z"
},
"unit_price": 1.99,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
}
]
}
],
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount_unrounded": 0.58,
"amount": 0.58,
"visible": true
}
],
"total_unrounded": 0.58,
"total": 0.58
},
"subtotal": 7.62,
"total": 8.2,
"notification_status": "open",
"site_info": {
"id": "9999999999999999",
"store_number": "9999"
},
"discount_total": 0,
"origin": "mobile",
"payment_status": "open",
"order_type": "order",
"creator": {
"time": "20YY-04-04T17:18:39.434Z",
"terminal": {
"id": "9"
}
},
"discount_info": {
"discounts": [],
"total": 0,
"total_unrounded": 0
},
"business_date": "20YY-04-04T00:00:00Z",
"time": {
"created": "20YY-04-04T17:18:39.434Z",
"last_modified": "2018-04-04T17:19:01.773Z",
"open": "20YY-04-04T17:19:01.736Z"
},
"destination": {
"id": "2",
"name": "Take Out"
},
"state": "open",
"version": "1",
"contributors": [
{
"time": "20YY-04-04T17:18:39.434Z",
"terminal": {
"id": "9"
}
}
],
"sequential_order_number": "1361",
"order_number": "2001361",
"_id": "9999999999999999",
"company_id": "9999999999999999"
},
"extended_info": {
"discounts_rejected": []
}
}Order Modifications
There are several options for modifying existing orders before they have been checked in. The topics below describe how to use the Online Ordering API to perform the following actions:
Substitute Items
Substitutions make it possible for customers to replace individual components of a group of items. For example, customers could order a salad instead of fries with their combo meal.
The steps below describe the general process for substitutions using the Data Management and Online Ordering APIs:
Work with your account manager to define combos and variations for products. Each product that includes variations will have
product_entity_idvalues listed in the [variations] array.Build an online menu in a way that offers combos and variations to the customers. Track the
product_idvalues of each item a customer selects.Send a PUT request to the Add Items endpoint with the substitute item included as a child item in the body of the request.
See the Substitutions Example topic for a walk-through of this process.
Substitutions Example
Each combo meal item definition contains a list of the default items that are included with the order. Each of the default items may include a list of accepted substitutions. Substitutions are defined when your account manager defines the combo item.
The example below shows the M-FRIES item definition. The product_entity_ids of each available substitution are listed in the [variations] array. The online menu will keep track of the product_id values of possible substitutions:
{
"items": [
{
"_id": "9999999999999999",
"effective_date": "20YY-02-15T11:38:41.762Z",
"entity_id": "9999999999999999",
"is_deleted": false,
"external_id": "130339",
"product_id": "130339",
"name": "M-FRIES",
"builds": [],
"external_category_ids": [],
"is_bundle": false,
"is_open_price": false,
"include_in_plain_builds": false,
"product_type": "standard",
"revenue_class": "default",
"modifier_collection_entity_id": "9999999999999999",
"reporting_category": {},
"variation_info": {
"variant_entity_id": "",
"parent_entity_id": "",
"variations": [
{
"variant_entity_id": "9999999999999999",
"product_entity_id": "999999999999999A"
},
{
"variant_entity_id": "9999999999999999",
"product_entity_id": "999999999999999B"
},
{
"variant_entity_id": "9999999999999999",
"product_entity_id": "999999999999999C"
},
{
"variant_entity_id": "9999999999999999",
"product_entity_id": "999999999999999D"
},
{
"variant_entity_id": "9999999999999999",
"product_entity_id": "999999999999999E"
},
{
"variant_entity_id": "9999999999999999",
"product_entity_id": "999999999999999F"
},
{
"variant_entity_id": "9999999999999999",
"product_entity_id": "999999999999999G""
}
]
},
"external_tag_ids": [
"151",
"161",
"511",
"946",
"1005"
],
"product_tag_entity_ids": [
"9999999999999999",
"9999999999999999",
"9999999999999999",
"9999999999999999",
"9999999999999999"
],
"tax_group_entity_id": "9999999999999999"
}
],
"total": 1,
"page_count": 1,
"current_page": 1,
"page_size": 100
}To substitute an item for one of the default items, send the product_id of the substitute item as a child item in the body of the Add Items request when adding the combo meal to the order. The example below shows the body of the Add Items request. The "product_id": "130341" refers to "L-ON RINGS" which is a substitute for the "M-FRIES" item:
{
"items": [{
"product_id": "130392",
"quantity": 1,
"child_items": [{
"product_id": "130347",
"quantity": 1
}, {
"product_id": "130341",
"quantity": 1
}, {
"product_id": "130128",
"quantity": 1
}]
}]
}The Add Items method responds with an order object. The order response below shows the combo meal with rings instead of fries:
{
"order": {
"items": [
{
"item_type": "standard",
"price": 0,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130392",
"name": "9999999999999999",
"time": {
"added": "20YY-03-27T19:58:16.647Z",
"last_modified": "20YY-03-27T19:58:16.767Z"
},
"unit_price": 0,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": [
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.28,
"amount_unrounded": 0.27345,
"visible": false
}
],
"total_unrounded": 0.27345,
"total": 0.28
},
"item_type": "standard",
"price": 3.64,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130347",
"name": "WB",
"time": {
"added": "20YY-03-27T19:58:16Z",
"last_modified": "20YY-03-27T19:58:16.767Z"
},
"unit_price": 3.64,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
},
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.19,
"amount_unrounded": 0.18706,
"visible": false
}
],
"total_unrounded": 0.18706,
"total": 0.19
},
"item_type": "standard",
"price": 2.49,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130341",
"name": "M-ON RINGS",
"time": {
"added": "20YY-03-27T19:58:16Z",
"last_modified": "20YY-03-27T19:58:16.767Z"
},
"unit_price": 2.49,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
},
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.15,
"amount_unrounded": 0.1495,
"visible": false
}
],
"total_unrounded": 0.1495,
"total": 0.15
},
"item_type": "standard",
"price": 1.99,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130128",
"name": "M-DRINK",
"time": {
"added": "20YY-03-27T19:58:16Z",
"last_modified": "20YY-03-27T19:58:16.767Z"
},
"unit_price": 1.99,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
}
]
}
],
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount_unrounded": 0.61001,
"amount": 0.62,
"visible": true
}
],
"total_unrounded": 0.61001,
"total": 0.62
},
"subtotal": 8.12,
"total": 8.74,
"notification_status": "open",
"site_info": {
"id": "9999999999999999",
"store_number": "99999"
},
"discount_total": 0,
"origin": "mobile",
"payment_status": "open",
"order_type": "order",
"creator": {
"time": "20YY-03-27T19:57:51.467Z",
"terminal": {
"id": "9"
}
},
"discount_info": {
"discounts": [],
"total": 0,
"total_unrounded": 0
},
"business_date": "20YY-03-27T00:00:00Z",
"time": {
"created": "20YY-03-27T19:57:51.467Z",
"last_modified": "20YY-03-27T19:58:16.785Z",
"open": "20YY-03-27T19:58:16.771Z"
},
"destination": {
"id": "2",
"name": "Take Out"
},
"state": "open",
"version": "1",
"contributors": [
{
"time": "20YY-03-27T19:57:51.467Z",
"terminal": {
"id": "9"
}
}
],
"sequential_order_number": "1330",
"order_number": "2001330",
"_id": "9999999999999999",
"company_id": "9999999999999999"
},
"extended_info": {
"discounts_rejected": []
}
}Modify Items
Modifiers make it possible for customers to place special orders like "no tomato" or "extra cheese".
Modifiers are defined as products and have unique product_id values. Each item that can be modified includes a [variations] array that lists the modifiers that apply to it.
Develop an online menu in a way that captures the product_id values of any modifiers that customers can select.
To add a modifier to an item, send the product_id of the modifier as a child item of the item that it modifies in the body of the Add Items request.
The Online Ordering API supports three different types of modifiers: Quantifiable Modifiers, Hybrid Modifiers, and Toggle Modifiers.
Quantifiable Modifiers: A modifier with the "Allow Modifier quantities to Change" setting set to "Yes" that has either no system variants or just a "No" variant. These modifiers cannot have custom variants. Quantifiable modifiers typically represent adding a certain amount of an ingredient to an item.
Hybrid Modifiers: A modifier with the "Allow Modifier quantities to Change" setting set to "Yes" that has both "No" and "Add" variants, as well as custom variants. Integrators can add hybrid modifiers to modifier builds as either quantifiable or toggle modifiers. Hybrid modifiers are more flexible in the types of modifications they can represent.
Toggle Modifiers: A modifier with the "Allow Modifier quantities to Change" setting set to "No." These modifiers can have either both system variants or only a "No" variant. Toggle modifiers with both system variants can have custom variants as well. Toggle modifiers typically represent making a single change to an item., either an ingredient or an aspect of preparation.
If the quantity of a child item is less than that of the parent item, Online Ordering API allows for fractional quantifies, which divide the quantity of the child item by the quantity of the parent item. The following example shows how an order stores items with a fractional quantity:
{
items: [
{
product_id: 'product_with_fractional_quantity',
quantity: 2, // NOTE: The integer rounded quantity
fractional_quantity: {
// NOTE: This property will represent the full quantity amount
in fractional format
"numerator":3,
"denominator":2
}
}
]
}Each product item has a configured "default build" which determines the modifiers that apply to the item by default. However, integrators can also create a "plain" build, which strips the item down to its most basic form, as well as any number of custom builds that each change the item in different ways through sets of modifiers. Custom builds can be replacement builds, which replace the default or plain build entirely, or augment builds, which add sets of modifiers on top of whichever replacement build is selected.
Note
Custom augment builds do NOT affect the overall price of the product, even if they contain modifiers that come with an added price. The order will not factor in the price of any modifiers within augment builds when calculating product prices.
The following example shows how an item can be set to the plain build in a order request:
"child_items": [
{
“build_type”:plain,
“item_type”: build
},
{
"entity_id": "build_entity_id",
“build_type”:replace,
“item_type”: build
},The following example shows a sample plain build:
{
"child_items": [
{
"entity_id": "plain_build_entity_id",
"_id": "999999999999999999999999",
"allow_plain_builds": true,
"allow_quantity": false,
"default_cost": 0,
"is_open_price": false,
"name": "Plain",
"product_id": "defaultBuild",
"product_type": "build",
"show_confirmaion_prompt": false,
"item_type": "build",
"unit_price": 0,
"quantity": 1,
"order_item_id": "999999999999999999999999",
"time": {
"added": "20YY-06-14T10:47:08.589Z",
"last_modified": "20YY-06-14T10:47:12.888Z"
},The following example shows a sample custom build:
{
"child_items": [
{
"entity_id": "999999999999999999999999",
"_id": "999999999999999999999999",
"allow_plain_builds": false,
"allow_quantity": false,
"default_cost": 0,
"is_open_price": false,
"name": "replace",
"product_id": "defaultBuild",
"product_type": "build",
"show_confirmaion_prompt": false,
"item_type": "build",
"unit_price": 0,
"quantity": 1,
"order_item_id": "999999999999999999999999",
"time": {
"added": "20YY-06-14T11:18:52.785Z",
"last_modified": "20YY-06-14T11:19:50.996Z"
},See the Modify Items Example topic for an example of how modifiers are added to and included in orders, and the Menu Engine Modifiers and Modifier Groups and Collections topics for additional information on modifiers and modifier builds.
Modify Items Example
The following example adds a sandwich to the order with an "Add Lettuce" modifier. Include the product_id of the "Add Lettuce" modifier in the body of the request to the Add Items endpoint. The body of the Add Item request is shown below:
{
"items": [{
"product_id": "130003",
"quantity": 1,
"child_items": [{"product_id":"146070", "quantity":1}]
}]
}The Add Items method responds with an order object that includes the sandwich and the modifier:
{
"order": {
"items": [
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.13,
"amount_unrounded": 0.13,
"visible": false
}
],
"total_unrounded": 0.13,
"total": 0.13
},
"item_type": "standard",
"price": 1.64,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130003",
"name": "X-FISH 1PC",
"time": {
"added": "20YY-03-23T20:23:27.955Z",
"last_modified": "20YY-03-23T20:23:28.209Z"
},
"unit_price": 1.64,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": [
{
"item_type": "modifier",
"price": 0,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "146070",
"name": "ADD LETTUC",
"time": {
"added": "20YY-03-23T20:23:27Z",
"last_modified": "20YY-03-23T20:23:28.209Z"
},
"unit_price": 0,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
}
]
}
],
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount_unrounded": 0.13,
"amount": 0.13,
"visible": true
}
],
"total_unrounded": 0.13,
"total": 0.13
},
"subtotal": 1.64,
"total": 1.77,
"notification_status": "open",
"site_info": {
"id": "9999999999999999",
"store_number": "99999"
},
"discount_total": 0,
"origin": "mobile",
"payment_status": "open",
"order_type": "order",
"creator": {
"time": "20YY-03-23T20:22:35.530Z",
"terminal": {
"id": "9"
}
},
"discount_info": {
"discounts": [],
"total": 0,
"total_unrounded": 0
},
"business_date": "20YY-03-23T00:00:00Z",
"time": {
"created": "20YY-03-23T20:22:35.530Z",
"last_modified": "20YY-03-23T20:23:28.272Z",
"open": "20YY-03-23T20:23:28.240Z"
},
"destination": {
"id": "2",
"name": "Take Out"
},
"state": "open",
"version": "1",
"contributors": [
{
"time": "20YY-03-23T20:22:35.530Z",
"terminal": {
"id": "9"
}
}
],
"sequential_order_number": "1206",
"order_number": "2001206",
"_id": "9999999999999999",
"company_id": "9999999999999999"
},
"extended_info": {
"discounts_rejected": []
}
}Each modifier product must be set up in the Data Management back end before it can be applied to a menu item.
Each menu item that accommodates the modifier must include the modifier in its "variations" attribute.
Donations
Online Ordering can include charitable donations as optional items, allowing integrators to collect donations for charitable organizations from customers during the ordering process. While the Menu Engine includes donations as menu items, they do not typically appear on the menu directly and are instead presented to customers by the point of sale during ordering.
Integrators can configure donations in Data Management with the help of our Professional Services team. Donation availability is configured by site, so a donation will be included on all menus that belong to its assigned sites.
Integrators can choose up to four default options for a donation's dollar amount, and an additional "Custom Amount" option will always be available. The point of sale will then present these options to the customer.
Taxes and discounts do not apply to donation items. The Online Ordering API can refund donations like any other standard item.
The Online Ordering API supports two types of donation items: dollar_amount donations and round_up_to_nearest_dollar donations.
"Dollar amount" donations include up to four set amount options and a custom amount option, as described above. The four selected options provide a default donation amount, but customers can always choose to donate a different amount with the custom option.
"Round up to nearest dollar" donations do not include amount options, and instead round the total amount of the customer's order up to the nearest dollar. The integrator collects the amount added as a charitable donation for their organization of choice.
An example request to the Online Ordering API to add donations to an order is shown below, including both a dollar_amount and round_up_to_nearest_dollar donation:
{
customer: {
id: '9999',
first_name: 'Customer',
last_name: 'Name',
phone_cell: '99999999',
phone_number: '9999999999',
},
store_number: '9999',
terminal: {
id: '9',
},
items: [
{
product_id: '999999',
quantity: 1,
},
{
donation_id: 'donation_id_1',
unit_price: 2.5,
apply_as: 'fixed',
},
{
donation_id: 'donation_id_2',
apply_as: 'round-up',
},
],
destination: {
name: 'dine-in',
id: 'Dine In',
},
}The Online Ordering API structures dollar_amount donations as follows:
{
"entity_id": "999999999999999999999999",
"item_type": "fee",
"name": "Charity Name",
"revenue_class": [],
"reporting_category": null,
"product_id": "9999",
"kitchen_routing_categories": [],
"quantity": 1,
"price": 2,
"unit_price": 2,
"segment_id": "999999999999999999999999",
"fee_config": {
"amount": 2,
"apply_as": "fixed",
"apply_pre_tax": false,
"fee_type": "donation"
},
"order_item_id": "999999999999999999999999",
"time": {
"added": "20XX-01-24T13:39:31.277Z",
"last_modified": "20XX-01-24T13:39:39.378Z"
},
"state": "pending",
"payment_status": "open",
"hash_code": "999999999999999999999999",
"fulfillment_status": "pending",
"child_items": [],
"tax_inclusive_price": 2
}
],
"subtotal": 2,
"tax_inclusive_subtotal": 2,
"fulfillment_status": "pending",
"discount_total": 0,
"tax_info": {
"taxes": [
{
"tax_definition_id": "999999999999999999999999",
"name": "Sales Tax",
"tax_inclusive": false,
"amount_unrounded": 0.165,
"amount": 0.17,
"marketplace_liable": false,
"external_id": "SalesTaxExternal"
}
],
"total_marketplace_liable_unrounded": 0,
"total_marketplace_liable": 0,
"total_inclusive_unrounded": 0,
"total_inclusive": 0,
"total_exclusive_unrounded": 0.165,
"total_exclusive": 0.17,
"total_unrounded": 0.165,
"total": 0.17
},
"total": 4.17,
"day_part_info": {
"day_part_type_id": null,
"day_part_type_name": null,
"external_id": null
},
"hash_code": "999999999999999999999999",
"lifecycle": "total",
"customer": {
"first_name": "",
"last_name": ""
},The Online Ordering API structures round_up_to_nearest_dollar donations as follows:
{
"entity_id": "999999999999999999999999",
"item_type": "fee",
"name": "Charity Name",
"revenue_class": [],
"reporting_category": null,
"product_id": "9999",
"kitchen_routing_categories": [],
"quantity": 1,
"price": 0.83,
"unit_price": 0.83,
"segment_id": "999999999999999999999999",
"fee_config": {
"amount": 0.83,
"apply_as": "round-up",
"apply_pre_tax": false,
"fee_type": "donation"
},
"order_item_id": "999999999999999999999999",
"time": {
"added": "20XX-01-24T13:45:04.615Z",
"last_modified": "20XX-01-24T13:45:11.206Z"
},
"state": "pending",
"payment_status": "paid",
"hash_code": "999999999999999999999999",
"fulfillment_status": "pending",
"child_items": [],
"tax_inclusive_price": 0.83
}
],
"subtotal": 2,
"tax_inclusive_subtotal": 2,
"fulfillment_status": "pending",
"discount_total": 0,
"tax_info": {
"taxes": [
{
"tax_definition_id": "999999999999999999999999",
"name": "Sales Tax",
"tax_inclusive": false,
"amount_unrounded": 0.165,
"amount": 0.17,
"marketplace_liable": false,
"external_id": "SalesTaxExternal"
}
],
"total_marketplace_liable_unrounded": 0,
"total_marketplace_liable": 0,
"total_inclusive_unrounded": 0,
"total_inclusive": 0,
"total_exclusive_unrounded": 0.165,
"total_exclusive": 0.17,
"total_unrounded": 0.165,
"total": 0.17
},
"total": 3,
"day_part_info": {
"day_part_type_id": null,
"day_part_type_name": null,
"external_id": null
},
"hash_code": "999999999999999999999999",
"lifecycle": "closed",
"customer": {
"first_name": "",
"last_name": ""
},See the Menu Engine Donations topic for information on how donations are stored in menus.
Discounts
The Online Ordering API supports two main types of discounts:
Item Level - Item level discounts reduce the price of a single item. Item level discount definitions include a list of the items that they can be applied to.
Order Level - Order level discounts reduce the price of an entire order.
Both types of discounts modify prices in one of the following ways:
Fixed Amount - Reduces the price of an item or order by a predefined amount.
Variable Amount - Reduces the price of an item or order by an amount sent in the body of the discount request.
Fixed Percent - Reduces the price of an item or order by a predefined percentage.
Variable Percent - Reduces the price of an item or order by a percentage sent in the body of the discount request.
Forced Price - Changes the subtotal or item price to a defined price.
Work with your account manager to define discounts in the Data Management portal. Each discount definition includes a discount_code attribute used to apply the discount to an order or item. To see a list of the current discounts, send a GET request to the Data Management /api/discount-definition/current endpoint.
Integrators can apply discounts to an order with either an Add Discount request or a Create Order request. When applying a discount in an Add Discount request, use the following structure:
{
"discounts": [
{"discount_code": "99999"}
]
}When applying a discount in a Create Order request, use the following structure:
{
...
"discount_info: {
"discounts": [
{"discount_code": "99999"}
]
}
}The Discount request returns an order object with the appropriate discount applied. The following topics provide examples of using item and order level discounts:
For information on $0.00 billing, see 100% Discount.
Item Level Discounts
To apply an item level discount, include the discount_info attribute with the item intended for the discount in the body of the Add Item request. The example below shows the body of an Add Item request including an item level discount:
{
"items": [{
"product_id": "999999",
"quantity": 1,
"discounts": [
{
"discount_code": "100",
"discount_variable_value": 0.5
}
]
}]
}The Add Item method responds with an order object with the discount applied to the item.
Order Level Discounts
There are two ways to apply an order level discount to an order:
Discount Method - Use the Discount Method to apply an order level discount to an existing order.
Create Order Method - Send the
discount_codein the discounts array as part of the body of the request that creates a new order.
Order Level Discount Example
The following example shows the body of a Create Order request that includes an order level discount:
{
"store_number": "test",
"terminal": {
"id": "9"
},
"items":[
{
"product_id":"9999",
"quantity":1,
"child_items": [
{
"product_id": "9999",
"quantity": 1
},
{
"product_id": "9999",
"quantity": 1
}
]
}
],
"customer":{
"id":"999999999999",
"first_name":"test",
"last_name":"test",
"phone_cell":"999999999999"
},
"discounts": [
{
"discount_code": "100",
"discount_variable_value": 0.5
}
]
}100% Discount
If a customer has a coupon that discounts the order to $0.00 in the point of sale (POS) system, use pay_type_id with a cash payment type and an amount of 0. This creates a 100% discount.
Note
The value for pay_type_id can vary. Determine the appropriate value for your system in Data Management.
Below is an example of the object to use in the Close Order operation. It adds a $0 payment to the order and closes it out.
{ "payments": [ { "amount": 0, "pay_type_id": "02" // Use the cash pay type value as listed in Data Management } ] }
Deletes
Send a delete request to the item, customer, or payment method endpoints to remove the respective element from the order. Deletes are useful for fixing mistakes in order entry or modifying orders that have their status property set to paid.
Delete requests return the following errors:
Error Response | Code: 66 Message: Failed to remove customer Code: 22 Message: Customer not found Code: 67 Message: Failed to remove item Code: 10 Message: Item not found Code: 54 Message: Failed to remove payment Code: 55 Message: Payment not found on order Code: 16 Message: Missed or Invalid Auth Token Code: 37 Message: Missing Company or Site ID in Header |
Delete Items
To delete items from an order, send a Delete request to the Item endpoint: {{mo_url}}/order/ORDER_ID/item. Include the order_item_id in the body of the request. The order_item_id is a unique identifier that ties the item to the order. The order_item_id is included as part of the order object that is returned when an item is added to the order.
The following example shows the Delete Items request body:
{
"order_item_ids": ["9999999999999999"]
}The Delete Items request returns an order object that denotes the item as deleted:
{
"order": {
"items": [],
"tax_info": {
"taxes": [],
"total_unrounded": 0,
"total": 0
},
"subtotal": 0,
"total": 0,
"notification_status": "open",
"site_info": {
"id": "9999999999999999",
"store_number": "99999"
},
"discount_total": 0,
"origin": "mobile",
"payment_status": "open",
"order_type": "order",
"creator": {
"time": "20YY-04-04T17:18:39.434Z",
"terminal": {
"id": "9"
}
},
"discount_info": {
"discounts": [],
"total": 0,
"total_unrounded": 0
},
"business_date": "20YY-04-04T00:00:00Z",
"time": {
"created": "20YY-04-04T17:18:39.434Z",
"last_modified": "20YY-04-04T18:59:10.376Z",
"open": "20YY-04-04T18:59:10.354Z"
},
"destination": {
"id": "2",
"name": "Take Out"
},
"state": "open",
"version": "1",
"contributors": [
{
"time": "20YY-04-04T17:18:39.434Z",
"terminal": {
"id": "9"
}
}
],
"deleted_items": [
{
"item_type": "standard",
"price": 0,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130392",
"name": "WB-ML",
"time": {
"added": "20YY-04-04T17:19:01.556Z",
"last_modified": "20YY-04-04T17:19:01.718Z"
},
"unit_price": 0,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": [
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.28,
"amount_unrounded": 0.27706,
"visible": false
}
],
"total_unrounded": 0.27706,
"total": 0.28
},
"item_type": "standard",
"price": 3.64,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130347",
"name": "WB",
"time": {
"added": "20YY-04-04T17:19:01Z",
"last_modified": "20YY-04-04T17:19:01.718Z"
},
"unit_price": 3.64,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
},
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.15,
"amount_unrounded": 0.15147,
"visible": false
}
],
"total_unrounded": 0.15147,
"total": 0.15
},
"item_type": "standard",
"price": 1.99,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130339",
"name": "M-FRIES",
"time": {
"added": "20YY-04-04T17:19:01Z",
"last_modified": "20YY-04-04T17:19:01.718Z"
},
"unit_price": 1.99,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
},
{
"tax_info": {
"taxes": [
{
"tax_definition_id": "9999999999999999",
"name": "MAIN",
"amount": 0.15,
"amount_unrounded": 0.15147,
"visible": false
}
],
"total_unrounded": 0.15147,
"total": 0.15
},
"item_type": "standard",
"price": 1.99,
"payment_status": "open",
"quantity": 1,
"tax_group": {
"entity_id": "9999999999999999"
},
"product_id": "130128",
"name": "M-DRINK",
"time": {
"added": "20YY-04-04T17:19:01Z",
"last_modified": "20YY-04-04T17:19:01.718Z"
},
"unit_price": 1.99,
"reporting_category": {},
"state": "open",
"order_item_id": "9999999999999999",
"entity_id": "9999999999999999",
"tags": [],
"child_items": []
}
]
}
],
"sequential_order_number": "1361",
"order_number": "2001361",
"_id": "9999999999999999",
"company_id": "9999999999999999"
},
"extended_info": {
"discounts_rejected": []
}
}Change Payment Methods
Follow the steps below to change the payment method associated with an order:
Delete the payment method currently applied to the order by sending a DELETE request to the Payment endpoint:
{{mo_url}}/order/ORDER_ID/payment.Add a new payment method by sending a PUT request to the Payment endpoint.
To delete a payment method associated with the order, send the value of the id attribute in the body of the DELETE request to the Payment endpoint. The id of the payment method is included in the order object returned when adding the payment method. The following example shows the body of the request:
{
"payment_ids": ["9999999999999999"]
}The method responds with an order object with the payment method removed. The order object does not indicate that a previous payment method was deleted.
To add a new payment method, follow the steps in the Add Payment topic.
Marketplace Facilitator Taxes
Because some states and territories require marketplace facilitators to collect and remit certain taxes, our tax calculator determines tax liability for each tax on an order individually. This topic describes the way that our system and marketplace facilitators are integrated to handle market facilitator tax liability.
Relevant Fields
The processes outlined in this topic use the following fields within the tax_info object:
marketplace_liable- Indicates if the marketplace facilitator is liable for a specific tax.total_marketplace_liable- Contains the total amount of tax for which the marketplace is liable, as calculated by our system.total_marketplace_liable_unrounded- Contains the total amount of tax for which the marketplace is liable, before rounding calculations.total_exclusive- Contains the total amount of tax on an order or item, as calculated by our system. This value is changed to match thecollected_exclusive_taxfield when that field is included.marketplace_remitted_tax- Contains the total amount of tax for which the marketplace is liable, as calculated by the integrator.collected_exclusive_tax- Contains the total amount of tax collected on an order by the integrator.collected_exclusive_tax_adjustment- Records the difference between the originaltotal_exclusivevalue and thecollected_exclusive_taxvalue.
Our Tax Calculation
The marketplace_liable flag in each tax definition indicates whether a particular tax should be remitted by the marketplace facilitator. Based on those values, the tax calculator automatically defines the total amount for which the marketplace is liable in the total_marketplace_liable field. The following example tax_info object displays the use of these fields:
"tax_info": {
"taxes": [{
"tax_definition_id": "9999999999999999",
"name": "State 1",
"tax_inclusive": false,
"amount_unrounded": 0.228,
"marketplace_liable": true,
//flag marking a specific tax as marketplace liable
"amount": 0.23
}, {
"tax_definition_id": "9999999999999999",
"name": "County 1",
"tax_inclusive": false,
"amount_unrounded": 0.228,
"marketplace_liable": false,
"amount": 0.23
}, {
"tax_definition_id": "9999999999999999",
"name": "County 2",
"tax_inclusive": false,
"marketplace_liable": false,
"amount_unrounded": 0,
"amount": 0
}, {
"tax_definition_id": "9999999999999999",
"name": "County 3",
"tax_inclusive": false,
"marketplace_liable": false,
"amount_unrounded": 0,
"amount": 0
}, {
"tax_definition_id": "9999999999999999",
"name": "County 4",
"tax_inclusive": false,
"marketplace_liable": false,
"amount_unrounded": 0,
"amount": 0
}, {
"tax_definition_id": "9999999999999999",
"name": "Meals",
"tax_inclusive": false,
"marketplace_liable": false,
"amount_unrounded": 0,
"amount": 0
}
],
"total_inclusive_unrounded": 0,
"total_inclusive": 0,
"total_exclusive_unrounded": 0.456,
"total_exclusive": 0.46,
"total_marketplace_liable_unrounded": 0.228, //Calculated from State 1 tax above
"total_marketplace_liable": 0.23, //Calculated from State 1 tax above
"total_unrounded": 0.456,
"total": 0.46
},
"tax_inclusive_price": 5.7The difference between the total_exclusive value and the marketplace_remitted_tax value is the amount of tax for which the merchant is liable.
Marketplace Facilitator Field Injection
Integrated marketplace facilitators can instead choose to calculate the amount of tax for which they are liable in their own tax calculator. In this case, the integrator may inject one or both of the following optional fields:
marketplace_remitted_tax: This field should contain the total amount of tax remitted by the marketplace facilitator, as calculated by the integrator.collected_exclusive_tax: This field should contain the total amount of tax that the integrator has collected for the order, including the amount within themarketplace_remitted_taxfield.
Implementation
The integrator can inject either or both of these fields into an order in a request to any of the following endpionts:
createOrder- The integrator can add the above fields to acreateOrderrequest only if it also includesunit_pricevalues for items.updateOrder- The integrator can add the above fields in anyupdateOrderrequest.addPayments- The integrator can add the above fields in anyaddPaymentsrequest.commitOrder- The integrator can add the above fields to acommitOrderrequest only for orders that do not yet have a payment added; the commit requests must also include a payment for the order.
The integrator must add these fields to an order within the tax_info object, as shown in the example order below:
{
"_id":"9999999999999999",
"order_type":"order",
"order_number":"600005",
"order_source":"Delivery Service",
"order_source_ext":{
"name":"Delivery Service",
"order_source_id":"4",
"is_marketplace": true,
"is_tax_liable": true
},
"subtotal":53.67,
"tax_inclusive_subtotal":53.67,
"discount_total":0,
"total":57.13,
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":2.7837,
"amount":2.79
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":1.06045,
"amount":1.06,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.26511,
"amount":0.26,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0.64733,
"total_inclusive":0.65,
"total_exclusive_unrounded":3.46193,
"total_exclusive":3.46,
"marketplace_remitted_tax":2.78,
"collected_exclusive_tax":3.46,
"total_unrounded":4.10926,
"total":4.11
},
"items":[
{
"order_item_id":"9999999999999999",
"item_type":"standard",
"name":"Old Fashioned",
"product_id":"30000001",
"tax_inclusive":true,
"price":9,
"unit_price":9,
"quantity":1,
"tax_inclusive_price":9,
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":0.43852,
"amount":0.44
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.16705,
"amount":0.17,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.04176,
"amount":0.04,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0.64733,
"total_inclusive":0.65,
"total_exclusive_unrounded":0,
"total_exclusive":0,
"total_unrounded":0.64733,
"total":0.65
}
},
{
"order_item_id":"9999999999999999",
"item_type":"standard",
"name":"Tomahawk Ribeye",
"product_id":"8100",
"tax_inclusive":false,
"price":35.99,
"unit_price":35.99,
"quantity":1,
"tax_inclusive_price":35.99,
"deleted_items":[],
"child_items":[
{
"order_item_id":"9999999999999999",
"product_id":"50100",
"name":"Rare",
"quantity":1,
"unit_price":0,
"price":0,
"item_type":"modifier",
"tax_inclusive_price":0
},
{
"order_item_id":"9999999999999999",
"item_type":"child",
"name":"Baked Potato",
"product_id":"3100",
"tax_group":{},
"tax_inclusive":false,
"price":0,
"unit_price":0,
"quantity":1,
"tax_inclusive_price":0,
"child_items":[
{
"quantity":1,
"price":0.69,
"unit_price":0.69,
"tax_inclusive":false,
"name":"Extra Bacon",
"product_id":"22003",
"item_type":"modifier",
"order_item_id":"9999999999999999",
"tax_inclusive_price":0.69,
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":0.03622,
"amount":0.04
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.0138,
"amount":0.01,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.00345,
"amount":0,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0,
"total_inclusive":0,
"total_exclusive_unrounded":0.05347,
"total_exclusive":0.05,
"total_unrounded":0.05347,
"total":0.05
}
}
]
},
{
"order_item_id":"9999999999999999",
"item_type":"child",
"name":"Sweet Potato",
"product_id":"3110",
"tax_inclusive":false,
"price":0,
"unit_price":0,
"quantity":1,
"tax_inclusive_price":0
}
],
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":1.88948,
"amount":1.89
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.7198,
"amount":0.72,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.17995,
"amount":0.18,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0,
"total_inclusive":0,
"total_exclusive_unrounded":2.78923,
"total_exclusive":2.79,
"total_unrounded":2.78923,
"total":2.79
}
},
{
"order_item_id":"9999999999999999",
"item_type":"standard",
"name":"Bowl French Onion Soup",
"product_id":"7010",
"tax_inclusive":false,
"price":7.99,
"unit_price":7.99,
"quantity":1,
"tax_inclusive_price":7.99,
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":0.41948,
"amount":0.42
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.1598,
"amount":0.16,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.03995,
"amount":0.04,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0,
"total_inclusive":0,
"total_exclusive_unrounded":0.61923,
"total_exclusive":0.62,
"total_unrounded":0.61923,
"total":0.62
}
}
]
}Collected Exclusive Tax Adjustment
In cases like the above example, where the integrator's collected_exclusive_tax value equals the total_exclusive value calculated by our system, Online Ordering does not need to modify the order any further.
When the integrator's collected_exclusive_tax value does not equal the total_exclusive value, our system automatically modifies the order to accommodate the fields submitted by the integrator. Our system updates the total_exclusive field to match the collected_exclusive_tax value and adds the collected_exclusive_tax_adjustment field, recording the difference between the collective_exclusive_tax and the original total_exclusive field.
The following example order displays these alterations:
{
"_id":"9999999999999999",
"order_type":"order",
"order_number":"600005",
"order_source":"Delivery Service",
"order_source_ext":{
"name":"Delivery Service",
"order_source_id":"4",
"is_marketplace": true,
"is_tax_liable": true
},
"subtotal":53.67,
"tax_inclusive_subtotal":53.67,
"discount_total":0,
"total":58.56,
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":2.7837,
"amount":2.79
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":1.06045,
"amount":1.06,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.26511,
"amount":0.26,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0.64733,
"total_inclusive":0.65,
"total_exclusive_unrounded":3.46193,
"total_exclusive":4.89,
"marketplace_remitted_tax":2.78,
"collected_exclusive_tax":4.89,
"collected_exclusive_tax_adjustment":1.43,
"total_unrounded":4.10926,
"total":5.54
},
"items":[
{
"order_item_id":"9999999999999999",
"item_type":"standard",
"name":"Old Fashioned",
"product_id":"30000001",
"tax_inclusive":true,
"price":9,
"unit_price":9,
"quantity":1,
"tax_inclusive_price":9,
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":0.43852,
"amount":0.44
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.16705,
"amount":0.17,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.04176,
"amount":0.04,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0.64733,
"total_inclusive":0.65,
"total_exclusive_unrounded":0,
"total_exclusive":0,
"total_unrounded":0.64733,
"total":0.65
}
},
{
"order_item_id":"9999999999999999",
"item_type":"standard",
"name":"Tomahawk Ribeye",
"product_id":"8100",
"tax_inclusive":false,
"price":35.99,
"unit_price":35.99,
"quantity":1,
"tax_inclusive_price":35.99,
"deleted_items":[],
"child_items":[
{
"order_item_id":"9999999999999999",
"product_id":"50100",
"name":"Rare",
"quantity":1,
"unit_price":0,
"price":0,
"item_type":"modifier",
"tax_inclusive_price":0
},
{
"order_item_id":"9999999999999999",
"item_type":"child",
"name":"Baked Potato",
"product_id":"3100",
"tax_inclusive":false,
"price":0,
"unit_price":0,
"quantity":1,
"tax_inclusive_price":0,
"child_items":[
{
"quantity":1,
"price":0.69,
"unit_price":0.69,
"tax_inclusive":false,
"name":"Extra Bacon",
"product_id":"22003",
"item_type":"modifier",
"order_item_id":"9999999999999999",
"tax_inclusive_price":0.69,
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":0.03622,
"amount":0.04
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.0138,
"amount":0.01,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.00345,
"amount":0,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0,
"total_inclusive":0,
"total_exclusive_unrounded":0.05347,
"total_exclusive":0.07,
"collected_exclusive_tax_adjustment":0.02,
"total_unrounded":0.05347,
"total":0.07
}
}
]
},
{
"order_item_id":"9999999999999999",
"item_type":"child",
"name":"Sweet Potato",
"product_id":"3110",
"tax_inclusive":false,
"price":0,
"unit_price":0,
"quantity":1,
"tax_inclusive_price":0
}
],
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":1.88948,
"amount":1.89
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.7198,
"amount":0.72,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.17995,
"amount":0.18,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0,
"total_inclusive":0,
"total_exclusive_unrounded":2.78923,
"total_exclusive":3.94,
"collected_exclusive_tax_adjustment":1.15,
"total_unrounded":2.78923,
"total":3.94
}
},
{
"order_item_id":"9999999999999999",
"item_type":"standard",
"name":"Bowl French Onion Soup",
"product_id":"7010",
"tax_inclusive":false,
"price":7.99,
"unit_price":7.99,
"quantity":1,
"tax_inclusive_price":7.99,
"tax_info":{
"taxes":[
{
"tax_definition_id":"9999999999999999",
"name":"NC - State Sales Tax",
"marketplace_liable": true,
"tax_inclusive":false,
"amount_unrounded":0.41948,
"amount":0.42
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - County of Mecklenburg Sales Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.1598,
"amount":0.16,
"tax_class":"sales_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"Mecklenburg County, NC",
"jurisdiction_type":"county_parish",
"external_id":""
}
},
{
"tax_definition_id":"9999999999999999",
"name":"NC - City of Charlotte Restaurant Tax",
"marketplace_liable": false,
"tax_inclusive":false,
"amount_unrounded":0.03995,
"amount":0.04,
"tax_class":"meal_tax",
"tax_jurisdiction":{
"entity_id":"9999999999999999",
"name":"City of Charlotte, NC",
"jurisdiction_type":"city_local",
"external_id":""
}
}
],
"total_inclusive_unrounded":0,
"total_inclusive":0,
"total_exclusive_unrounded":0.61923,
"total_exclusive":0.88,
"collected_exclusive_tax_adjustment":0.26,
"total_unrounded":0.61923,
"total":0.88
}
}
]
}Modifier Builds
Modifier builds allow you to save a specific selection of modifiers to shorten order taking time. The modifier build types are described below:
Default: This build determines the modifiers that apply to the item by default.
Plain: This build strips the item down to its most basic form, as well as any number of custom builds that each change the item in different ways through the sets of modifiers.
Paid Quick: This build includes an upcharge or discount for the modifier. It also maintains pricing functions at the product level, including child-item pricing.
Custom: This build can be a replacement build which replaces the default or plain build entirely, or it can be an augment build which adds sets of modifiers on top of whichever replacement build is selected.
For more information on modifiers, go to Modifiers and Modifier Groups and Collections in the Menu Engine API documentation.
Portal Settings
To create or edit a modifier build in the Portal, navigate to → → → → . The screen displays a New Modifier Build form, which is described in the table below. The New Modifier Build form contains five sections:
General
The General section contains the following elements:
Element Name | Field Type | Bulk | Required | Available Values | Default Values |
|---|---|---|---|---|---|
Tile Name | text | Not applicable | Not applicable | Not applicable | General |
Name | text input | No | Yes | Alpha-numeric characters and space (" ") | Not applicable |
Build Type | drop-down | No | Yes | Augment, Replacement | Replacement |
Active | toggle | Yes | No | Active, Inactive | Inactive |
Modifiers
The Modifiers section contains the following elements:
A "Modifiers" tile containing the following three elements:
Element Name
Field Type
Description
Add Modifiers
button
When you click the "Add Modifiers" button, the "Add Modifiers" modal window opens up
Search
search bar component
Perform a search by the modifier name
Modifiers
table
Contains four columns: Modifier, Modifier ID, Quantifiable, and Quantity.
Each item of the table has a checkbox at the beginning of the line.
The "Modifier" table has the following four columns:
Column
Field Type
Available Values
Default Value
Behavior
Modifier
text
A sortable field, not editable
Modifier ID
text
Not editable
Quantifiable
toggle
Yes, No
No
It is shown when a modifier is "Quantifiable." Otherwise, it is not shown.
Quantity
input field
It is equal to the "Increment Modifier Quantity By" of a selected modifier
When the "Quantifiable" toggle is set to "No" or is not shown, this column must be empty.
When the "Quantifiable" toggle is set to "Yes," this column must contain the +/- controls to increase or decrease the quantity. The step is equal to the "Secondary Increment" of the modifier if configured or the "Increment Modifier Quantity By."
Pricing
The Pricing section contains the following elements:
Element Name | Field Type | Bulk | Required | Available Values | Default Values |
|---|---|---|---|---|---|
Tile Name | text | Not applicable | Not applicable | Not applicable | Price |
Tax Inclusive | toggle | Yes | No | Enabled, Disabled | Disabled |
Tax Group | dropdown | No | No | A list of tax groups configured by the company | |
Subtract Price on Modifier Removal | toggle | No | No | Enabled, Disabled | Disabled |
Pricing Method | dropdown | No | No | Not Priced, Sum Modifier Prices | Not Priced |
Roll Up Price | dropdown | No | No | Do Not Roll Up, Roll Up After Tax, Roll Up Before Tax | Do Not Roll Up |
When the “Pricing Method” = “Sum Modifier Prices,” the following fields are exposed: “Subtract Price on Modifier Removal,” "Roll Up Price," "Tax Inclusive," and "Tax Group."
When the “Pricing Method” = “Not Priced,” the above mentioned fields are hidden.
Kitchen
The Kitchen section contains the following elements:
Element Name | Field Type | Bulk | Required | Available Values | Default Values |
|---|---|---|---|---|---|
Tile Name | text | Not applicable | Not applicable | Kitchen | Not applicable |
Preparation Instructions | rich text editor | No | No | Not applicable |
Modifier Collections
The Modifier Collections section contains the following elements:
Component Name | Field Type | Description |
|---|---|---|
Modifier Collections | table | Contains two columns: Modifier Collection and Modifier Collection ID. They are sortable. |
Search | search bar component | Perform a search by the Modifier Collections' names |
For more information on modifiers, see Modifiers and Modifier Groups and Collections in the Menu Engine API documentation.
Paid Quick Build
Paid Quick builds include an upcharge or discount for the modifier. It also maintains pricing functions at the product level, including child-item pricing.
The price of the modifiers can be associated with builds in the same way they are associated with products, and the prices for builds will be calculated and returned by the price engine for both the point of sale (POS) and Online Ordering. These prices are subject to tax, therefore, the association of the tax groups to the modifier-build objects and the tax inclusivity flag, to the builds and their prices, is supported.
Enable Paid Quick Builds
The steps below describe the process to enable a paid quick build:
Navigate to → → → → .
Select an existing item or click the New Modifier Build button.
Select Pricing from the left navigation pane.
From the Pricing section, use the dropdown menu to select Sum Modifier Prices, which activates additional fields.
Select the option for Subtract Price on Modifier Removal by clicking the toggle, Yes to enable and No to disable.
From the dropdown menu, select the appropriate options for Roll Up Price. The options include the following:
Do Not Roll Up
Roll Up After Tax
Roll Up Before Tax
Select the option for Tax Inclusive by clicking the toggle, Yes to enable and No to disable.
From the dropdown menu, select a Tax Group. The options include the following:
Non-Taxable
Prepared
Pre-packaged
Venue Food Tax
Venue Beverage Tax
Venue Liquor Tax
Ohio
When an item with a custom build is added to the order, the Online Ordering API calculates the build price based on the sum of modifiers applied to this build.
For more information on Pricing settings, see Pricing in the Menu Engine API documentation.
Submit an Order with Include Build Modifiers in Quantity
The Include Build Modifiers in Quantity logic, for both Calculate Build Inclusive Quantity and Fractional Build Inclusive Quantity, is described below:
Depending on the "Include Build Modifiers in Quantity" setting state, the modifiers in the item should be added to the
qty_build_inclusiveorfractional_qty_build_inclusive. If the "Include Build Modifiers in Quantity" setting is true and the order should contain the total quantity of added modifiers. For example, the default quantity included in the build + the manually added quantity.When the "Include Build Modifiers in Quantity" is false, you should not add any extra quantity fields and process the modifiers as normal (existing behavior).
An example of the logic is described in the table below. The default quantity is set to 3 in this example.
Build Modifiers in Quantity | Pricing | Modifier Element of the Order | Build | Total Quantity | Total Price |
|---|---|---|---|---|---|
True | x1 Tomato = $1 | { product_id: "tomato", quantity: 2 } | $2 | 5 tomatoes | $3 |
False | x1 Tomato = $1 | { product_id: "tomato", quantity: 2 } | $2 | 3 tomatoes | $3 |
Enable Include Build Modifiers in Quantity Setting
The steps below describe the process to enable the Include Build Modifiers in Quantity setting:
Navigate to → → → → → → → → .
Toggle Yes for Include Build Modifiers in Quantity.
Submit an Order with Include Build Items on Child-Item Modifier Pricing Rules
The Include Build Items on Child-Item Modifier Pricing Rules logic is described below:
When the “Include Build Items” toggle is enabled in the Portal in the Child-Item Modifier Pricing Rules settings, the quantity of the modifiers in the build should be taken into account for the modifier child-item pricing.
When the “Include Build Items” toggle is disabled in the Portal in the Child-Item Modifier Pricing Rules settings, the quantity of modifiers in the build should not be taken into account for the modifier child-item pricing.
Test Cases
Case | Prerequisites | Include Build Items | Result |
|---|---|---|---|
1 |
| Yes | The additional Modifier Sugar is priced $0.4 (one (1) sugar) considering the modifier in the default build and Build B |
2 |
| No | The additional Modifier Sugar is priced $0.5 (one (1) sugar) ignoring the modifier in the default build and Build B |
Enable Include Build Items on Child-Item Modifier Pricing Rules
The steps below describe the process to enable the Include Build Items on Child-Item Modifier Pricing Rules setting:
Navigate to → → → → → .
Select an existing item or click the New Modifier button.
Select Pricing from the left navigation pane.
Click the Add Child-Item Modifier Pricing Rule button.
Under Pricing in the Child-Item Pricing Rules modal window, set the Quantity Based toggle to Yes to activate the Include Build Items toggle.
Set the activated Include Build Items toggle to Yes.
For more information on pricing rules, see Pricing in the Menu Engine API documentation.
Submit an Order with Subtract Price on Modifier Removal
The Subtract Price on Modifier Removal parameter decreases the price when the quantity is decreased when enabled. The parameter logic is set based on the following:
If the "Subtract Price on Modifier Removal" parameter in the custom build configuration is disabled (false), then the custom build price should not be changed from the default when the negative quantity or negative fractional quantity value is received for any modifier from that build.
If the "Subtract Price on Modifier Removal" parameter in the custom build configuration is enabled (true), then the custom build price should be changed from the default when the negative quantity or negative fractional quantity value is received for any modifier from that build.
Enable Subtract Price on Modifier Removal Parameter
The steps below describe the process to enable the Subtract Price on Modifier Removal parameter:
Navigate to → → → → .
Select an existing item or click the New Modifier Build button.
Select Pricing from the left navigation pane.
From the Pricing section, use the dropdown menu to select Sum Modifier Prices.
Set the Subtract Price on Modifier Removal toggle to Yes.
For more information on Pricing settings, see Pricing in the Menu Engine API documentation.
Submit an Order with Decreasing Quantity from the Build
In order to decrease the quantity of the modifier in the build and decrease the build price (if the Subtract Price on Modifier Removal setting is enabled), send the negative quantity values of the modifiers which are already added to the build with a default quantity applied. This can apply to both regular and fractional quantities. For example, to decrease the default quantity of 2 by half, the numerator is -1 and the denominator is 2. The quantity changes to 1.
A sample code snippet of fractional_quantity is shown below:
{ entity_id: '649d8c3c6c18078e7a585140', fractional_quantity: { numerator: -3, denominator: 1, }, }
Enable Allow Modifier Quantities to Change
The steps below describe the process to enable the Allow Modifier Quantities to Change setting:
Navigate to → → → → → .
Select an existing item or click the New Modifier button.
Under the General section, scroll down to Options.
Under Options, set the Allow Modifier Quantities to Change toggle to Yes.
Submit an Order with an Empty Plain Build
Adding an empty plain build allows you to remove the default build for an item and it allows items without any predefined options.
Enable Plain Builds
To add an empty plain build, you need to enable plain builds. The steps below describe the process to enable plain builds:
Navigate to → → → → .
Select an existing item or click the New Product button.
Select Build from the left navigation pane.
From the Build section, use the dropdown menu to select the appropriate option. The options include:
None - This option does not activate the Enable Plain Build toggle.
Sandwich Modifiers
Drink Modifiers
Burger Modifiers
Basic Modifiers
Under Default Build Modifiers, set the Enable Plain Build toggle to Yes.
When the empty plain build is applied, the default build identifier is excluded from the item and none of the builds should be applied. An example of the request using the POST/order endpoint is shown below. It contains a "Double Salad" product_id with the empty build applied. The entity_id of a plain build can be any value because it is not pulled from Data Management.
--header 'Content-Type: application/json' \ --header 'Authorization: TOKEN' \ --header 'X-Company-Id: 5e8b37a8a029bf000aae9f83' \ --header 'X-Site-Ids: 5e8b37c8c330e1000ae1d0de' \ --data-raw '{ "store_number": "61000", "terminal": { "id": "9" }, "items": [ { "product_id": "Double Salad", "quantity": 1, "child_items": [ { "entity_id": "64e730849475818d2263e6b1", "build_type": "plain", "item_type": "build", "quantity": 1 } ] } ], "customer": { "id": "30562060", "first_name": "Jen", "last_name": "Kenobi", "phone_cell": "8005555309", "loyalty_customer": false, "email": "j.k@company.com" }, "reference_id": "dba260af-16d0-41ad-b901-08ce06816b35" }'
Enable Include in Plain Builds
To add an item to a plain build, follow the steps below to enable the Include in Plain Builds setting:
Navigate to → → → → → .
Select an existing item or click the New Modifier button.
Under the General section, scroll down to Options.
Under Options, set the Include in Plain Builds toggle to Yes.
Order Segment
Order segments allow integrators to divide orders into segments for a variety of purposes, including dividing orders between multiple customers. Segments make it easy to allocate individual parts of an order to the intended customer by associating a name with each segment.
The order object includes a segments array containing multiple OrderSegment objects, each of which has an ID corresponding to a segment_id field within an order item. Each segment also contains a segment_title field. Integrators may set a default title for each segment (e.g. Seat, Tray, Bag, etc.), but the POS may also treat every segment name as a custom segment name, providing the ability to enter a customer name for each segment_title field.
Pricing
The Online Ordering API supports the following configuration options for pricing products and modifiers, availability within Data Management:
Pricing Settings: These settings determine the basic price info for the item.
Open Price: Determines if the item prompts the user for a price when added to an order, rather than having a set price.
Tax Inclusive: Defines if the item's price is tax inclusive or not.
Price: Sets the price of the item at each site.
Roll Up Price: Determines if the price of the item should roll up to a parent item before tax, after tax, or not at all. When the price of a child-item rolls up to the parent item, the parent-item price includes the price of the child-item in calculations and displays.
Pricing Rule Settings: These settings allow integrators to create and manage rules for altering the item's price under certain conditions.
Name: Defines the name of the pricing rule.
Tax Inclusive: Determines whether or not the pricing rule includes applicable taxes.
Price Adjustment: Determines if the pricing rule replaces or adds to the item's default price.
Adjustment Value: Defines the amount of the price adjustment.
Roll Up Price: See above.
Conditions: Sets the conditions under which the pricing rule applies.
Any Order Sources: Determines if the rule applies to all order sources. If no, the user can define which order sources the rule applies to.
Any Time Period: Determines if the rule applies to all time periods. If no, the user can define which time periods the rule applies to.
Child-Item Pricing Rule Settings: These settings allow integrators to create and manage rules for altering the item's price under certain conditions when the item is a child-item.
Name: Defines the name of the pricing rule.
Choose Products: Determines which products the item must be attached to as a child-item for the rule to apply. The user can choose products individually or by tag.
Tax Inclusive: Determines whether or not the pricing rule includes applicable taxes.
Quantity Based: Allows integrators to configure the pricing rule with multiple price adjustments, each attached to a different quantity range for the child-item.
Price Adjustment: Determines if the pricing rule replaces or adds to the item's default price.
Adjustment Value: Defines the amount of the price adjustment.
Roll Up Price: See above.
Conditions: Sets the conditions under which the pricing rule applies.
Any Order Sources: Determines if the rule applies to all order sources. If no, the user can define which order sources the rule applies to.
Cost: Sets the default cost of the item at each site.
The Online Ordering API stores items with quantity-based pricing as follows:
{
allowed_order_source_entities: [],
allowed_order_source_entity_ids: [],
allowed_order_source_ids: [],
apply_type: 'adjust',
child_product_entities: [
{
entity_id: '9999999999999999",
name: 'Test product (to remove)',
product_id: 'Test product',
_id: '9999999999999999",
},
],
child_product_entity_ids: ['9999999999999999"],
child_type: 'child-product',
company_id: '9999999999999999",
created_at: '20YY-05-25T13:38:40.119Z',
created_by: '9999999999999999",
entity_id: '9999999999999999",
is_active: true,
is_master: true,
is_quantity_based: true,
mappings: [
{
child_product_entity_ids: ['9999999999999999"],
company_id: '9999999999999999",
created_at: '2021-05-25T13:38:40.219Z',
created_by: '9999999999999999",
document_id: '9999999999999999",
effective_date: '20YY-05-25T00:00:00.000Z',
entity_id: '9999999999999999",
is_active: true,
parent_product_entity_ids: ['9999999999999999"],
product_entity_id: null,
site_id: '9999999999999999",
transaction_id: '9999999999999999",
updated_at: '20YY-05-25T13:38:40.219Z',
updated_by: '9999999999999999",
_id: '9999999999999999",
},
],
name: 'Quantity Based Child Price',
parent_product_entity_ids: ['9999999999999999"],
parent_products: [
{
entity_id: '9999999999999999",
name: 'Small Dutch Freeze',
product_id: '99999',
_id: '9999999999999999",
},
],
priority: 1,
product_entity_id: '9999999999999999",
quantity_group_id: '9999999999999999",
range_end: 2,
range_start: 1,
roll_up_price: 'do_not_roll_up',
site_ids: ['9999999999999999"],
tax_inclusive: false,
tax_inclusive_sync_params: {sync: false},
transaction_id: '9999999999999999",
type: 'child-quantity-product',
unit_price: 11.25,
updated_at: '20YY-05-25T13:38:40.119Z',
updated_by: '9999999999999999",
use_alternative_item_price: false,
_id: '9999999999999999",
}Comment Items
Online Ordering supports the ability for customers to input comments on their orders, providing the kitchen employees at the destination site with personalized instructions for preparing an order.
Online Ordering can process comments for an order, a parent item, or a child item, allowing integrators to choose at what menu level and step of the ordering process customers can enter comments. For example, an online ordering application could include a comment field for each product in an order, or a point of sale (POS) employee could input a comment about the entire order from the customer during the ordering process in-store.
Regardless of how the customer submits the comment, Online Ordering processes comments differently for various POS systems:
For IRIS POS, an order includes customer comments as a comment string field, which can be included in the order object or in an order item object. This structure allows the comment field to be added to an order, product, or modifier.
For POS API, Online Ordering formats the comment as a child-item of the entity described. The level at which the comment item is added to the order depends on the parent entity; for example, a comment describing a product would be added as a child-item at the modifier level. The order will structure the comment item as follows:
{
'quantity': 1,
'price': 0,
'unit_price': 0,
'name': 'Item Level Comment',
'entity_id': '9999',
'product_id': 'defaultComment',
'item_type': 'comment',
'comment': 'customer's comment for the kitchen'
};The following sample shows the different ways of including a comment, either on the whole order or on a particular item:
{
"customer": {
"first_name": "customer first name",
"id": "999999999999999999999999",
"last_name": "customer last name",
"phone_cell": "9999999999"
},
"store_number": "test",
"terminal": {
"id": "9"
},
"comment": "order level comment goes here",
"items": [
{
"product_id": "99999",
"name": "Orange",
"comment": "Item level comment goes here",
//this comment will display even if the following is also included
"child_items": [
{
"product_id": "12345",
"item_type": "comment",
"name": "comment",
"description": "item level comment goes here"
// The actual comment you make will show in the description
}
]
}
]
}The following sample shows an example order with a comment item included:
{
"items": [{
"product_id": "12345",
"quantity": 1,
"price": 0,
"unit_price": 0,
"comment": "Item Level Comment",
// Note that we still keep the current way of adding comments
...,
"child_items": [{
"quantity": 1,
"price": 0,
"unit_price": 0,
"name": "Item Level Comment",
// XPOS expects to have this as the actual comment
"entity_id": "1234",
"product_id": "defaultComment",
"item_type": "comment",
"comment": "customer's comment for the kitchen",
"order_item_id": "999999999999999999999999",
"time": {
"added": "20YY-04-23T17:07:59.271Z",
"last_modified": "20YY-04-23T17:07:59.290Z",
"pending": "20YY-04-23T17:07:59.272Z"
},
"state": "pending",
"payment_status": "open",
"hash_code": "999999999999999999999999",
"child_items": [],
"tax_inclusive_price": 0
}
]
}
]
}Child Item Sorting by Order Source
Child item sorting allows integrators to customize how items are displayed on the point of sale (POS) terminal screen. The default setting is By Name, which is sorted alphabetically.
The steps below describe the process to enable child item sorting based on the order source:
Navigate to → → → → .
From Preferences, select Edit site preferences.
If multiple sites are displayed, select the appropriate site(s).
From the landing page, select the Online Ordering dropdown menu.
Toggle Yes for Child Item Sorting by Order Source.
From Online Ordering, select Add Order Source. A new window displays.
Select the Order Source from the following options:
In-Store
Mobile
Web
Kiosk
Select the Sorting Method option by clicking the dropdown menu. Select from the following options:
By Name - Sorting alphabetically
User-Defined Order - Customized
Data Driven - Determined by the POS terminal button placement
Click Add 1 Order Source. If more than one option is selected, the button text includes that number. For example, select two Order Source options and the button displays "Add 2 Order Sources."
The settings are saved. To remove the option, select X next to the Order Source.
Expo Numbers for Injected Orders
Expo numbers are shortened numbers on a point of sale (POS) terminal. Our system has added this feature to online orders. The Expo number comprises the terminal number and the last two digits of the order number.
The steps below describe the process to enable Expo numbers for injected orders:
Navigate to → → → → .
From Preferences, select Edit site preferences.
If multiple sites are displayed, select the appropriate site(s).
From the landing page, select the Online Ordering dropdown menu.
From Online Ordering, select the Expo Numbers for Inject Orders dropdown menu.
Toggle Yes for Expo Numbers for Inject Orders.
The setting is saved. To remove the setting, toggle No.