--- sidebar_label: 'Basket and items' sidebar_position: 4 --- # Basket and items An order's basket is the set of line items the guest has added, together with any discounts applied and the payment and totals that close out the order. This article explains how items are structured, how discounts are represented, and how to read the payment and total fields. :::info Refer to the [order property reference](../orders/order-properties.md) for a complete and detailed overview of an order's properties. ::: ## Items The `items` array contains every line item in the order. Each item is either a **menu item** (a product from the menu) or a **charge item** (such as a delivery fee or service charge). The `type` field distinguishes them: | `type` value | Description | |---|---| | `menuItem` | A product from the menu | | `chargeItem` | A charge such as tip, delivery fee, service charge | Charge items carry an additional `subItemType` field that identifies the charge: | `subItemType` value | Description | |---|---| | `tip` | Gratuity added by the guest | | `deliveryFee` | Delivery charge | | `serviceCharge` | Revenue service charge | | `nonRevenueServiceCharge` | Non-revenue service charge | | `none` | Not a charge item (used on all `menuItem` entries) | ### Item tree structure Items are nested. A top-level item in `items` represents a product the guest added directly. Modifier and component selections sit inside the item's `configItems` array, which can itself contain further `configItems`. This mirrors the product configuration structure in the menu. Items are always structured so that the first item in the tree is a non-container, the second level (if present) is a container, the third is a non-container, and so on alternating down the tree. - Item - Config item (isContainer: true) - Config item (isContainer: false) - Config item (isContainer: true) - Config item (isContainer: false) ### Unit IDs Every item carries a `unitIds` map. Unit IDs are the mechanism for referring to a specific unit of an item, an item which has a total quantity of two will have two unit IDs. An items total quantity is the sum of its own `quantity` field and the quantities of all its ancestor items in the tree. This is important when discounts or integrations need to target an individual unit rather than the item type as a whole. #### Unit ID format A unit ID is the item's `id` followed by a zero-based index: `.`. With `quantity: 1` there is always exactly one unit ID, suffixed `.0`. With `quantity: 2` there would be two: `.0` and `.1`. #### How the map is keyed The key in `unitIds` depends on where the item sits in the tree: - **Top-level items** (direct children of `order.items`): the key is the item's own `id` with no suffix. - **Child items** (`configItems` at any depth): the key is the **parent item's unit ID** (`.`). This means you can read any item's `unitIds` and immediately know which specific unit of the parent it belongs to, without traversing the entire tree. #### Example Below is a simplified trace of a item and its `configItems`: ```text item - Burger Product (isContainer: false) id: a606b2a7 quantity: 2 unitIds: { "a606b2a7": ["a606b2a7.0", "a606b2a7.1"] } ↑ key = own id (top-level rule) configItem - Select Size (isContainer: true) id: 6f54ae01 quantity: 1 unitIds: { "a606b2a7.0": ["6f54ae01.0"], "a606b2a7.1": ["6f54ae01.1"] } ↑ key = parent's first unit ID configItem - 150g Burger (isContainer: false) id: e646d0c0 quantity: 2 unitIds: { "6f54ae01.0": ["e646d0c0.0", "e646d0c0.1"], "6f54ae01.1": ["e646d0c0.2", "e646d0c0.3"] } configItem - Change bread (isContainer: true) id: 0455ae00 quantity: 1 unitIds: { "e646d0c0.0": ["0455ae00.0"], "e646d0c0.1": ["0455ae00.1"], "e646d0c0.2": ["0455ae00.2"], "e646d0c0.3": ["0455ae00.3"] } configItem - Sesame Bread (isContainer: false) id: 0d59b405 quantity: 1 unitIds: { "0455ae00.0": ["0d59b405.0"], "0455ae00.1": ["0d59b405.1"], "0455ae00.2": ["0d59b405.2"], "0455ae00.3": ["0d59b405.3"] } ``` Each level's key is the unit ID of the item directly above it in the tree. Following the keys upward reconstructs the full ancestry of any item. #### Unit IDs in discounts Discounts reference unit IDs to identify which specific ordered copy of an item received a reduction. The `relatedItemUnitIds` and `discountedItemUnitId` fields on a discount entry both use the same `.` format: ```json { "relatedItemIds": ["46de377d-2c2f-4d3f-9891-dc97cbc2b2fa"], "relatedItemUnitIds": ["46de377d-2c2f-4d3f-9891-dc97cbc2b2fa.0"], "amounts": [ { "discountedItemId": "46de377d-2c2f-4d3f-9891-dc97cbc2b2fa", "discountedItemUnitId": "46de377d-2c2f-4d3f-9891-dc97cbc2b2fa.0", "amount": 2000 } ] } ``` If the same item appeared twice in the basket, each copy would have its own unit ID (`.0` and `.1`), and `discountedItemUnitId` disambiguates which copy received the discount. ### Pricing Every item has a `price` object. Prices are expressed **per unit** in the smallest currency unit (e.g. hundredths of the local currency). To calculate the contribution of an item to the order total, multiply `price.amount` by `quantity` and sum recursively from root to leaf. ```json { "price": { "amount": 11100, "isVatIncluded": true, "vat": [ { "type": "12%", "percent": 12 } ] } } ``` `isVatIncluded: true` means the `amount` already includes VAT. The `vat` array breaks down the applicable VAT rates. ### Mapping details Each item includes a `mappingDetails` object. This is opaque data your integration can use to correlate order items with records in a system (e.g. a POS). The fields present in `mappingDetails` vary by integration configuration and are configured in the menu item. :::info See [Menu items](../menus/items.md) for how products and containers are configured in a menu and how they relate to items in an order. ::: ## Discounts The `discounts` array lists every discount applied to the order. Each discount entry describes a discount that was applied to one or more items. A single discount can span multiple items. ```json { "id": "5b8feb5c-6679-478f-b3b3-d2e575dd0e94", "dealId": "36d19189-d67f-4468-bf41-96613302ff3c", "title": "Discount for 2x Coffee", "relatedItemIds": ["46de377d-2c2f-4d3f-9891-dc97cbc2b2fa"], "relatedItemUnitIds": ["46de377d-2c2f-4d3f-9891-dc97cbc2b2fa.0", "46de377d-2c2f-4d3f-9891-dc97cbc2b2fa.1"], "amounts": [ { "discountedItemId": "46de377d-2c2f-4d3f-9891-dc97cbc2b2fa", "discountedItemUnitId": "46de377d-2c2f-4d3f-9891-dc97cbc2b2fa.0", "amount": 2000, "vat": [{ "type": "12%", "percent": 12 }] }, { "discountedItemId": "46de377d-2c2f-4d3f-9891-dc97cbc2b2fa", "discountedItemUnitId": "46de377d-2c2f-4d3f-9891-dc97cbc2b2fa.1", "amount": 2000, "vat": [{ "type": "12%", "percent": 12 }] } ], "postVat": false } ``` Key fields: | Field | Description | |---|---| | `dealId` | The deal that generated this discount | | `title` | Display name of the discount | | `amounts` | Per-item breakdown of the discount value | | `amounts[].amount` | Discount value in the smallest currency unit (positive number) | | `amounts[].discountedItemId` | ID of the item that received the discount | | `amounts[].discountedItemUnitId` | ID of the specific unit of the item that received the discount | | `postVat` | `true` if the discount is applied after VAT is calculated; `false` if applied before | ## Payments and totals ### Payments The `payments` array holds the payment transactions. Each entry represents one payment. The most integration-relevant field is `paymentMethod`, which describes how the guest paid: | `paymentMethod.type` | Description | |---|---| | `minimal` | Basic payment method with a name only | | `paymentCard` | Physical or digital card (includes masked card number, expiry, issuer, and brand) | | `bankAccount` | Bank account (includes masked account number and bank name) | | `emvPaymentCard` | EMV card with additional chip-level tag data | ```json { "amount": 15800, "paymentProviderId": "adyen", "paymentMethod": { "type": "paymentCard", "name": "ApplePay", "cardInfo": { "maskedCardNumber": "527484******4934", "cardExpiry": "2901", "cardIssuer": "mc_applepay", "cardBrand": "Mastercard" } } } ``` `amount` is in the smallest currency unit. Use `currencyIsoCode` and `currencyDecimalDigits` from the order root to format it correctly. ### Totals Three top-level fields summarise the monetary value of the order: | Field | Description | |---|---| | `total` | Gross order value (includes VAT). | | `subtotal` | Net order value (excludes VAT).| | `discountTotal` | Total discount applied, expressed as a **negative** value. | All three are integers in the smallest currency unit. Example from an order with SEK currency and `currencyDecimalDigits: 2`: ```json { "total": 15800, "subtotal": 14107, "discountTotal": -12000, "currencyIsoCode": "SEK", "currencyDecimalDigits": 2 } ``` This represents a gross total of 158.00 SEK, a net total of 141.07 SEK, and a discount of −120.00 SEK.