Get menus

{
  "data": [
    {
      "id": "lunch-delivery",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "brand_id": null,
      "merchant_id": "22222222-2222-2222-2222-222222222222",
      "store_id": "downtown",
      "store_uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "channel_id": "app",
      "channel_uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "fulfillment_id": "delivery",
      "fulfillment_uid": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
      "name": { "en_us": "Lunch delivery menu" },
      "description": { "en_us": "Weekday lunch items for app delivery" },
      "schedules": [
        { "day_of_week": "monday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] },
        { "day_of_week": "tuesday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] },
        { "day_of_week": "wednesday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] },
        { "day_of_week": "thursday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] },
        { "day_of_week": "friday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] }
      ],
      "products": [
        {
          "id": "burger-classic",
          "name": { "en_us": "Classic burger" },
          "description": { "en_us": "Angus beef patty with lettuce and tomato." },
          "image_url": "https://cdn.example.com/burger-classic.jpg",
          "cms_template_id": null,
          "status": "ACTIVE",
          "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,
            "modifiers": [],
            "modifier_group_ids": ["choose-drink"]
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        },
        {
          "id": "soda",
          "name": { "en_us": "Soda" },
          "description": null,
          "image_url": null,
          "cms_template_id": null,
          "status": "ACTIVE",
          "bundled_items": [],
          "pricing": {
            "minimum_quantity": 0,
            "maximum_quantity": 1,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 0,
            "anchor_price": 0,
            "anchor_price_percentage": 0,
            "modifiers": [],
            "modifier_group_ids": []
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        },
        {
          "id": "cola",
          "name": { "en_us": "Cola" },
          "description": null,
          "image_url": null,
          "cms_template_id": null,
          "status": "ACTIVE",
          "bundled_items": [],
          "pricing": {
            "minimum_quantity": 0,
            "maximum_quantity": 1,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 0,
            "anchor_price": 0,
            "anchor_price_percentage": 0,
            "modifiers": [],
            "modifier_group_ids": []
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        }
      ],
      "categories": [
        {
          "id": "mains",
          "name": { "en_us": "Mains" },
          "description": { "en_us": "Burgers and sandwiches" },
          "image_url": "https://cdn.example.com/mains.jpg",
          "cms_template_id": null,
          "status": "ACTIVE",
          "items": [{ "type": "PRODUCT", "id": "e5f6a7b8-c9d0-1234-ef56-789012345678" }],
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        }
      ],
      "modifier_groups": [
        {
          "id": "choose-drink",
          "title": { "en_us": "Choose a drink" },
          "description": null,
          "display_type": "LIST",
          "modifier_ids": ["cola", "soda"],
          "minimum_quantity": 0,
          "maximum_quantity": 1,
          "charge_above_quantity": null,
          "metadata": {}
        }
      ],
      "metadata": {},
      "cms_template_id": null,
      "cms": null,
      "status": "ACTIVE",
      "release": "v2026-07-10-21h"
    }
  ]
}

Returns every menu available for the customer’s current selling context. Pass fulfillment_id, store_id, channel_id, and brand_id to load catalogs for that combination. When any parameter is omitted, or when no menu exists for the combination, Fire spark falls back to the merchant-wide default menu (fulfillment_id, store_id, channel_id, and brand_id all __ANY__). When store_id, channel_id, and fulfillment_id are all provided (and not __ANY__), Fire spark checks that those entities exist and are ACTIVE (and that brand_id is ACTIVE when provided). An inactive or missing scope returns 422 with details.issues[] of { code: "SCOPE_INACTIVE", field } where field is store_id, channel_id, fulfillment_id, or brand_id. When multiple menus share the same context and their schedules match the current time, Fire spark returns all of them in data. Menus with schedules: null are always available. When no menu is currently in schedule, Fire spark returns every menu in data whose next availability window is closest to the current time. If several menus share that same next start time, all of them are returned.

Requires a Fire spark access token obtained through token exchange. The token scopes requests to the authenticated customer and merchant.

Query parameters

Parameter	Required	Description
`fulfillment_id`	No	External fulfillment identifier (for example `delivery`, `pickup`). Alphanumeric characters, `_`, and `-` only. 1–64 characters. Omit to receive the default menu.
`store_id`	No	External store identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters. Omit to receive the default menu.
`channel_id`	No	External channel identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters. Omit to receive the default menu.
`brand_id`	No	External brand identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters. Omit to receive the default menu.
`streaming`	No	When `true`, respond with NDJSON (one menu per line) instead of one JSON body. Defaults to `false`. Accepts `true` / `1` / `false` / `0`.
`category_limit`	No	Max flattened categories in the first stream line. Integer 1–50. Default `10`. Only applies when `streaming=true`.
`product_limit`	No	Max sellable products per fold category in the first stream line. Integer 1–100. Default `10`. Only applies when `streaming=true`.

Request

curl "https://firespark.cloud/api/storefront/v1/menus?fulfillment_id=delivery&store_id=downtown&channel_id=app&brand_id=0001" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Streaming

Omit streaming (or send false) to keep the single JSON response below. With streaming=true, Fire spark returns Content-Type: application/x-ndjson. Each line is { "data": Menu[] } with one menu. Upsert by id (later line wins); do not replace the list.

Fold of the first menu. The first category_limit categories in display order (depth-first, same as the storefront nav), each with up to product_limit sellable products. Each of those products includes its full customization tree (modifier_groups, nested modifiers, and bundled_items) so a customer can open customization immediately. recommendations is [].
Full first menu. The complete first menu from the non-streaming payload.
Remaining menus. One full menu per line, in catalog order.

404 and 422 stay JSON and are decided before the stream opens.

curl "https://firespark.cloud/api/storefront/v1/menus?fulfillment_id=delivery&store_id=downtown&channel_id=app&brand_id=0001&streaming=true" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response

The response wraps an array of menu objects in data. Only ACTIVE menus are returned. When at least one menu is in schedule now, every matching menu is included. Otherwise, Fire spark includes the menu or menus whose next scheduled window starts soonest.

{
  "data": [
    {
      "id": "lunch-delivery",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "brand_id": null,
      "merchant_id": "22222222-2222-2222-2222-222222222222",
      "store_id": "downtown",
      "store_uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "channel_id": "app",
      "channel_uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "fulfillment_id": "delivery",
      "fulfillment_uid": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
      "name": { "en_us": "Lunch delivery menu" },
      "description": { "en_us": "Weekday lunch items for app delivery" },
      "schedules": [
        { "day_of_week": "monday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] },
        { "day_of_week": "tuesday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] },
        { "day_of_week": "wednesday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] },
        { "day_of_week": "thursday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] },
        { "day_of_week": "friday", "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }] }
      ],
      "products": [
        {
          "id": "burger-classic",
          "name": { "en_us": "Classic burger" },
          "description": { "en_us": "Angus beef patty with lettuce and tomato." },
          "image_url": "https://cdn.example.com/burger-classic.jpg",
          "cms_template_id": null,
          "status": "ACTIVE",
          "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,
            "modifiers": [],
            "modifier_group_ids": ["choose-drink"]
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        },
        {
          "id": "soda",
          "name": { "en_us": "Soda" },
          "description": null,
          "image_url": null,
          "cms_template_id": null,
          "status": "ACTIVE",
          "bundled_items": [],
          "pricing": {
            "minimum_quantity": 0,
            "maximum_quantity": 1,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 0,
            "anchor_price": 0,
            "anchor_price_percentage": 0,
            "modifiers": [],
            "modifier_group_ids": []
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        },
        {
          "id": "cola",
          "name": { "en_us": "Cola" },
          "description": null,
          "image_url": null,
          "cms_template_id": null,
          "status": "ACTIVE",
          "bundled_items": [],
          "pricing": {
            "minimum_quantity": 0,
            "maximum_quantity": 1,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 0,
            "anchor_price": 0,
            "anchor_price_percentage": 0,
            "modifiers": [],
            "modifier_group_ids": []
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        }
      ],
      "categories": [
        {
          "id": "mains",
          "name": { "en_us": "Mains" },
          "description": { "en_us": "Burgers and sandwiches" },
          "image_url": "https://cdn.example.com/mains.jpg",
          "cms_template_id": null,
          "status": "ACTIVE",
          "items": [{ "type": "PRODUCT", "id": "e5f6a7b8-c9d0-1234-ef56-789012345678" }],
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        }
      ],
      "modifier_groups": [
        {
          "id": "choose-drink",
          "title": { "en_us": "Choose a drink" },
          "description": null,
          "display_type": "LIST",
          "modifier_ids": ["cola", "soda"],
          "minimum_quantity": 0,
          "maximum_quantity": 1,
          "charge_above_quantity": null,
          "metadata": {}
        }
      ],
      "metadata": {},
      "cms_template_id": null,
      "cms": null,
      "status": "ACTIVE",
      "release": "v2026-07-10-21h"
    }
  ]
}

Field	Type	Description
`id`	string	External menu identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters.
`uid`	string (UUID)	Fire spark internal identifier.
`brand_id`	string \| null	External brand identifier. `null` when the resource is not brand-scoped.
`merchant_id`	string (UUID)	Fire spark merchant identifier.
`store_id`	string	External store identifier.
`store_uid`	string (UUID)	Fire spark store identifier.
`channel_id`	string	External channel identifier.
`channel_uid`	string (UUID)	Fire spark channel identifier.
`fulfillment_id`	string	External fulfillment identifier.
`fulfillment_uid`	string (UUID)	Fire spark fulfillment identifier.
`name`	object	Localized display name keyed by locale (for example `en_us`). Each value is 1–1024 characters.
`description`	object \| null	Localized description keyed by locale. `null` when omitted. Each value is 1–1024 characters.
`schedules`	array \| null	Weekly schedule entries. `null` when there is no schedule restriction.
`products`	array	Products in this menu. Use Get product for full detail.
`categories`	array	Categories in this menu. Use Get category for full detail.
`modifier_groups`	array	Modifier groups referenced by products in this menu.
`variant_groups`	array	Variant groups referenced by products in this menu. Only options whose products are in the menu are included.
`metadata`	object	Partner-specific metadata. Defaults to `{}`.
`cms_template_id`	string (UUID)	CMS template linked to this menu. `null` when no template is assigned.
`cms`	object	Read-only. Resolved CMS template when `cms_template_id` is set.
`status`	string	`ACTIVE` or `INACTIVE`. Only `ACTIVE` menus are returned.
`release`	string	Release id that published this menu.

schedules

An array of schedule entries, or null when there is no schedule restriction. Each entry represents one day of the week:

Field	Required	Type	Description
`day_of_week`	Yes	string	`monday` through `sunday`.
`periods`	Yes	array	One or more time windows when the menu is active on that day.

Each period:

Field	Required	Type	Description
`closed`	No	boolean	`true` when this period is closed. Defaults to `false`.
`start_time`	Conditional	string	ISO time (for example `11:00:00`). Required unless `closed` is `true`.
`end_time`	Conditional	string	ISO time (for example `15:00:00`). Required unless `closed` is `true`.
`start_date`	No	string \| null	ISO 8601 datetime, or `null` for the always-on fallback. Set together with `end_date`.
`end_date`	No	string \| null	ISO 8601 datetime, or `null` for the always-on fallback. Set together with `start_date`.

products

Each product in a composed menu includes catalog fields plus context-specific pricing and availability:

Field	Required	Type	Description
`id`	Yes	string	External product identifier.
`name`	Yes	object	Localized display name keyed by locale (for example `en_us`).
`description`	No	object \| null	Localized description. `null` when omitted.
`image_url`	No	string	Product image URL. `null` when omitted.
`cms_template_id`	No	string (UUID)	CMS template linked to this product. `null` when not assigned.
`status`	Yes	string	`ACTIVE` or `INACTIVE`.
`bundled_items`	No	array	Items included in a bundle or combo. Defaults to `[]`.
`pricing`	Yes	object	Price, tax, quantity limits, and modifier configuration. See pricing.
`availability`	Yes	object	Product availability. See fields below.
`metadata`	No	object	Partner-specific metadata. Defaults to `{}`.

Each availability object:

Field	Required	Type	Description
`status`	Yes	string	`AVAILABLE`, `HIDDEN`, or `OUT_OF_STOCK`.
`schedules`	No	array \| null	Schedule entries with `day_of_week` and `periods`. `null` when there is no schedule restriction.
`out_of_stock_until`	No	string	Optional ISO 8601 datetime when the product returns to stock.

Each bundled_items entry:

Field	Required	Type	Description
`id`	Yes	string	External identifier of the bundled product.
`refund_price`	Yes	number	Refund amount when the customer removes this item from the bundle. ≥ 0.
`included_quantity`	Yes	number	Units included by default. ≥ 0.

Example product

{
  "id": "burger-classic",
  "name": { "en_us": "Classic burger" },
  "description": { "en_us": "Angus beef patty with lettuce and tomato." },
  "image_url": "https://cdn.example.com/burger-classic.jpg",
  "cms_template_id": null,
  "status": "ACTIVE",
  "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,
    "modifiers": [],
    "modifier_group_ids": ["choose-drink"]
  },
  "availability": {
    "status": "AVAILABLE",
    "schedules": null,
    "out_of_stock_until": null
  },
  "metadata": {}
}

categories

Each category in a composed menu:

Field	Required	Type	Description
`id`	Yes	string	External category identifier.
`name`	Yes	object	Localized display name keyed by locale.
`description`	No	object \| null	Localized description. `null` when omitted.
`image_url`	No	string	Category image URL. `null` when omitted.
`cms_template_id`	No	string (UUID)	CMS template linked to this category. `null` when not assigned.
`status`	Yes	string	`ACTIVE` or `INACTIVE`.
`items`	No	array	Ordered category entries. Defaults to `[]`.
`availability`	Yes	object	Category availability. See fields below.
`metadata`	No	object	Partner-specific metadata. Defaults to `{}`.

Each entry in items:

Field	Required	Type	Description
`type`	Yes	string	`CATEGORY` or `PRODUCT`.
`id`	Yes	string	External category or product identifier.

Each availability object:

Field	Required	Type	Description
`status`	Yes	string	`AVAILABLE`, `HIDDEN`, or `OUT_OF_STOCK`.
`schedules`	No	array \| null	Schedule entries with `day_of_week` and `periods`. `null` when there is no schedule restriction.
`out_of_stock_until`	No	string	Optional ISO 8601 datetime when the product returns to stock.

Example category

{
  "id": "mains",
  "name": { "en_us": "Mains" },
  "description": { "en_us": "Burgers and sandwiches" },
  "image_url": "https://cdn.example.com/mains.jpg",
  "cms_template_id": null,
  "status": "ACTIVE",
  "items": [{ "type": "PRODUCT", "id": "e5f6a7b8-c9d0-1234-ef56-789012345678" }],
  "availability": {
    "status": "AVAILABLE",
    "schedules": null,
    "out_of_stock_until": null
  },
  "metadata": {}
}

modifier_groups

Each modifier group in a composed menu:

Field	Required	Type	Description
`id`	Yes	string	External modifier group identifier. Referenced from `pricing.modifier_group_ids`.
`title`	Yes	object	Localized group title keyed by locale.
`description`	No	object \| null	Localized description. `null` when omitted.
`display_type`	No	string	`GRID` or `LIST`.
`modifier_ids`	Yes	array	Product UUIDs for modifiers in this group. At least 2 entries.
`minimum_quantity`	Yes	number	Minimum selections required. ≥ 0.
`maximum_quantity`	Yes	number	Maximum selections allowed. 0–1,000,000.
`charge_above_quantity`	No	number	Number of free selections before additional charges apply. Optional.
`metadata`	No	object	Partner-specific metadata. Defaults to `{}`.

Example modifier group

{
  "id": "choose-drink",
  "title": { "en_us": "Choose a drink" },
  "description": null,
  "display_type": "LIST",
  "modifier_ids": ["cola", "soda"],
  "minimum_quantity": 0,
  "maximum_quantity": 1,
  "charge_above_quantity": null,
  "metadata": {}
}

variant_groups

Each variant group:

Field	Required	Type	Description
`id`	Yes	string	External variant group identifier. Referenced from `pricing.variant_group_ids`.
`title`	Yes	object	Localized question keyed by locale.
`description`	No	object \| null	Localized description.
`display_type`	No	string	`GRID` or `LIST`.
`variants`	Yes	array	Options in this group. 1–100 entries. See fields below.
`metadata`	No	object	Partner-specific metadata. Defaults to `{}`.

Each entry in variants:

Field	Required	Type	Description
`id`	Yes	string	Option identifier, unique across all variant groups. Referenced from `pricing.variants[].variant_group_option_ids`.
`name`	Yes	object	Localized option label keyed by locale.
`description`	No	object \| null	Localized description.
`image_url`	No	string \| null	Option image URL, served from Firespark storage like product images.
`product_ids`	Yes	array	Variant products this option can lead to. Each must exist and list this option in its `pricing.variants`. 1–1000 entries.
`metadata`	No	object	Partner-specific metadata. Defaults to `{}`.

Example variant group

{
  "id": "size",
  "title": { "en_us": "Size" },
  "description": null,
  "display_type": "GRID",
  "variants": [
    { "id": "medium", "name": { "en_us": "Medium" }, "description": null, "image_url": null, "product_ids": ["pep-m-thin", "pep-m-thick"], "metadata": {} },
    { "id": "large", "name": { "en_us": "Large" }, "description": null, "image_url": null, "product_ids": ["pep-l-thin", "pep-l-thick"], "metadata": {} }
  ],
  "metadata": {}
}

pricing

Product pricing in a composed menu:

Field	Required	Type	Description
`minimum_quantity`	Yes	number	Minimum units per order. ≥ 0.
`maximum_quantity`	Yes	number	Maximum units per order. 0–1,000,000.
`is_tax_inclusive`	Yes	boolean	Whether `price` includes tax.
`tax_rate`	Yes	number	Tax rate as a decimal (for example `0.15` for 15%). 0–1.
`price`	Yes	number	List price. ≥ 0.
`anchor_price`	Yes	number	Reference price for strikethrough or comparison. ≥ 0.
`anchor_price_percentage`	Yes	number	Discount shown relative to `anchor_price`. 0–1.
`starting_price`	No	number \| null	Lowest price reachable once required modifiers are chosen. Show it as “From $X” when it is higher than `price`. `null` or absent means show `price`.
`modifiers`	No	array	Per-modifier pricing overrides. Defaults to `[]`.
`modifier_group_ids`	No	array	External modifier group identifiers attached to this product. Defaults to `[]`.
`variant_group_ids`	No	array	Variant groups asked on this base product. Each id must exist in `variant_groups` and appear once. A product with variant groups can’t have `modifier_group_ids`. Defaults to `[]`. See Variants.
`variants`	No	array	When this product is a variant: one entry per base, each `{ "product_id": base id, "variant_group_option_ids": [...] }` with exactly one option from every group on the base. Defaults to `[]`.

Each modifiers entry adds:

Field	Required	Type	Description
`modifier_group_id`	Yes	string	External modifier group identifier.
`default_quantity`	Yes	number	Pre-selected quantity. ≥ 0.
`charge_above_quantity`	No	number	Free selections before charges apply. Optional.
`display_type`	No	string	`RADIO`, `CHECKBOX`, or `QUANTITY`.

Error responses

Status	Description
`400`	Missing or invalid query parameters.
`401`	Missing or invalid access token.
`403`	Token does not have access to this merchant’s menus.
`404`	No active menu found for the requested context, and no menu has a future schedule window.

API Documentation

Endpoints

Guides

Resources

Query parameters

Request

Streaming

Response

Menu object

Error responses

​Query parameters

​Request

​Streaming

​Response

​Menu object

​Error responses

Query parameters

Request

Streaming

Response

Menu object

Error responses