Combos & bundles · Nexus Gateway

A meal can have a size, an included drink and a paid extra. The menu distinguishes those choices so you can price and submit the exact configured combination.

Three kinds of choice

Group kind	Meaning	Pricing
`variant`	Defines the product configuration, such as size or crust.	Match all defining choices to one published variant. Its price, published discount and deposit replace the base values.
`bundle`	An included component, such as the meal’s drink.	Included in the meal price. Add its deposit, if any.
`extra`	An optional addition, such as extra sauce.	Add its price and deposit. This is the default kind when omitted.

Match a published variant exactly

Collect the selected group_id/option_id pairs from every kind: "variant" group.
Compare that set, ignoring order, to each variants[].selections set.
Require exactly one matching, available variant. Its price minus its published discount, plus its deposit, are the base for this configuration.
Enforce every group’s bounds and availability, including bundle choices and extras.

Individually valid choices may form an invalid combination. A large size and a particular crust can both exist without their combination being configured. Never manufacture a variant or sum defining-choice prices.

For a product with no variants, use its base price minus its published discount, plus its deposit. A fixed bundle can have one variant whose selections are empty; that variant supplies the base amounts. Implicit fixed components are already represented by the published meal, including their deposits. Do not invent extra order lines for them.

Worked example: two large burger meals

The sample menu offers regular and large meals. The customer selects large, water, and extra sauce for each of two meals, with delivery.

Large variant3,000 bani

Water · included, with deposit50 bani

Extra sauce200 bani

Packaging100 bani

Per meal × 23,350 × 2 = 6,700

Delivery · once per order700 bani

Order total7,400 bani 74.00 RON

order-delivery.json

{
  "external_order_id": "shop-1002",
  "menu_revision": "example-menu-1",
  "currency": "RON",
  "fulfillment": "delivery",
  "customer": {
    "name": "Example Customer",
    "phone": "0700000000"
  },
  "address": {
    "city": "Iași",
    "street": "Example Street 10",
    "details": "Apartment 2, ring the bell"
  },
  "payment": {
    "method": "cash_on_fulfillment"
  },
  "items": [
    {
      "product_id": "burger-meal",
      "quantity": 2,
      "modifiers": [
        {
          "group_id": "size",
          "option_id": "large"
        },
        {
          "group_id": "drink",
          "option_id": "water"
        },
        {
          "group_id": "meal-extras",
          "option_id": "sauce"
        }
      ]
    }
  ],
  "total": 7400
}

Download order-delivery.json ↓

Submit choices, not calculated identities

Send all selected choices in items[].modifiers, including variant, bundle and extra choices. Each pair may appear only once per line and applies once to each unit on that line. For two meals with different choices, use two lines with quantity one.

Do not send variant_id or prices in an order line. The gateway finds the exact variant itself and checks your total; unknown fields are rejected. The cart guide has a tested function that applies all of these rules.

When a combination stops being available

variant_unavailable, modifier_unavailable and modifier_selection_invalid require a menu/cart review. Re-fetch the menu, remove unavailable choices, and obtain customer confirmation. If the original submission timed out, recover it with its saved body first; do not silently replace its choices.