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 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: <item.id>.<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 (<parentId>.<index>).

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:

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 <item.id>.<index> format:

{
  "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.

{
  "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 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.

{
  "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

{
  "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:

{
  "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.