Nested categories

This example shows the smallest useful category tree: a root section that contains two child categories, each listing one product. There are no modifier groups — only navigation structure. Use it when you want browse sections like Food → Burgers / Sides without complicating the payload.

What this example includes

Entity	Count	Purpose
Products	2	One burger and one side
Categories	3	One root category and two nested subcategories
Modifier groups	0	None — structure only
Menus	1	All-day delivery menu linked to the root category

Request

Call Upsert menus with style: DEFAULT. Nest subcategories by adding entries with "type": "CATEGORY" in the parent category’s items array. List products only on the leaf categories.

curl --request PUT \
  --url 'https://firespark.cloud/api/integrations/v1/menus?fulfillment_id=delivery&store_id=downtown&channel_id=app&brand_id=0001' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @nested-categories.json

nested-categories.json

{
  "style": "DEFAULT",
  "products": [
    {
      "id": "classic-burger",
      "name": { "en_us": "Classic burger" },
      "description": { "en_us": "Angus beef patty with lettuce and tomato." },
      "image_url": "https://cdn.example.com/classic-burger.jpg",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 12.99,
        "anchor_price": 14.99,
        "anchor_price_percentage": 0.13,
        "modifier_group_ids": [],
        "modifiers": []
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "fries",
      "name": { "en_us": "Seasoned fries" },
      "description": { "en_us": "Crispy fries with house seasoning." },
      "image_url": "https://cdn.example.com/fries.jpg",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 4.99,
        "anchor_price": 4.99,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": []
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    }
  ],
  "categories": [
    {
      "id": "food",
      "name": { "en_us": "Food" },
      "description": { "en_us": "Browse by section" },
      "items": [
        { "type": "CATEGORY", "id": "burgers" },
        { "type": "CATEGORY", "id": "sides" }
      ],
      "availability": {
        "status": "ACTIVE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "burgers",
      "name": { "en_us": "Burgers" },
      "description": { "en_us": "Beef and chicken burgers" },
      "items": [{ "type": "PRODUCT", "id": "classic-burger" }],
      "availability": {
        "status": "ACTIVE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "sides",
      "name": { "en_us": "Sides" },
      "description": { "en_us": "Sides and snacks" },
      "items": [{ "type": "PRODUCT", "id": "fries" }],
      "availability": {
        "status": "ACTIVE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    }
  ],
  "modifier_groups": [],
  "menus": [
    {
      "id": "all-day-delivery",
      "name": { "en_us": "All-day delivery" },
      "description": { "en_us": "Standard delivery menu" },
      "schedules": null,
      "metadata": {},
      "category_ids": ["food"],
      "status": "ACTIVE"
    }
  ]
}

Key points

Link the menu to the root only. menus[].category_ids lists food. Fire spark resolves nested categories from there.
Use type: CATEGORY to nest. The parent food category does not list products directly — it points to burgers and sides.
Put products on leaf categories. classic-burger and fries appear in items with "type": "PRODUCT" on the subcategories that customers open.
Order matters. items order is the display order within each category.
Depth limit. Category nesting supports up to 3 levels including the root linked from the menu. This example uses two category levels under the menu.

Simple menu

Flat category with modifier groups

Menu sync guide

Full validation rules

Upsert menus

API reference

API Documentation

Endpoints

Guides

Resources

What this example includes

Request

Key points

Simple menu

Categories

Menu sync guide

Upsert menus

​What this example includes

​Request

​Key points

​Related

Simple menu

Categories

Menu sync guide

Upsert menus

What this example includes

Request

Key points

Related