List menus

{
  "data": [
    {
      "id": "lunch-delivery",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merchant_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "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 composed menus for the authenticated merchant. Pass scope query parameters to narrow results to a selling context. Each composed menu is keyed by fulfillment_id + store_id + channel_id + brand_id + menu.id — the same dimensions as Upsert menus. This endpoint does not filter by schedule. It returns every ACTIVE menu that matches the resolved scope, regardless of the current time. Use Get menu when you need the customer-facing menu for the current order time.

Requires an access token with the menus:read scope. See Token to obtain a token.

Query parameters

Parameter	Required	Description
`fulfillment_id`	No	External fulfillment identifier. When set, returns menus for that fulfillment type only. Omit to include every fulfillment type in the resolved store and channel scope. See List fulfillment.
`store_id`	No	External store identifier. Returns menus scoped to this store. Omit or pass `__ANY__` for the merchant-wide default.
`channel_id`	No	External channel identifier. Returns menus scoped to this channel. Omit or pass `__ANY__` for all channels.
`brand_id`	No	External brand identifier. Omit or pass `__ANY__` for the merchant-wide default. When set, returns menus scoped to this brand only.
`menu_id`	No	External menu identifier. When set, returns one composed menu. Omit to return every menu that matches the other scope parameters — for example lunch and dinner schedules under the same store and channel.

Omitting fulfillment_id, store_id, channel_id, or brand_id does not return menus from every store, channel, or brand. Each resolves to the wildcard scope stored as __ANY__, matching Upsert menus. Use menu_id when you need to narrow further within that scope.

Request

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

Response

The response wraps an array of menu objects in data. Each menu is scoped to one store, channel, and fulfillment combination and includes the composed catalog structure and weekly schedule. All matching menus are returned, including those outside their active schedule window.

{
  "data": [
    {
      "id": "lunch-delivery",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merchant_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "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. Unique per scope (`fulfillment_id`, `store_id`, `channel_id`, `brand_id`).
`uid`	string (UUID)	Fire spark internal identifier.
`merchant_id`	string (UUID)	Merchant the menu belongs to.
`store_id`	string	External store identifier this menu applies to.
`store_uid`	string (UUID)	Fire spark store identifier.
`channel_id`	string	External channel identifier this menu applies to.
`channel_uid`	string (UUID)	Fire spark channel identifier.
`fulfillment_id`	string	External fulfillment identifier this menu applies to.
`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 composed menu. See the products accordion below.
`categories`	array	Categories in this composed menu. See the categories accordion below.
`modifier_groups`	array	Modifier groups in this composed menu. See the modifier_groups accordion below.
`variant_groups`	array	Variant groups in this composed menu. See the variant_groups accordion below.
`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. `null` when `cms_template_id` is `null`. When set, the resolved CMS template for this menu.
`status`	string	`ACTIVE` or `INACTIVE`.
`release`	string	Release id that published this menu (from `x-release-id` on sync).

schedules

An array of schedule entries, or null when there is no schedule restriction. When present, the array must contain exactly 7 entries — one per weekday from monday through sunday — with no duplicate days and no overlapping periods on the same day.Each entry:

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. At most 10 per 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 with offset, or `null` for the always-on fallback. Set together with `end_date`.
`end_date`	No	string \| null	ISO 8601 datetime with offset, 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	Reference “From” price. Calculated during sync when the integration omits it; `null` means it is never shown. ≥ 0.
`modifiers`	No	array	Per-group pricing and selection 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 object in modifiers configures one modifier group referenced in modifier_group_ids. It accepts the same pricing fields as the parent product, plus modifier-specific fields:

Field	Required	Type	Description
`modifier_group_id`	Yes	string	External modifier group identifier. Must match a group in `modifier_group_ids`.
`minimum_quantity`	Yes	number	Minimum units per order for modifiers in this group. ≥ 0.
`maximum_quantity`	Yes	number	Maximum units per order for modifiers in this group. 0–1,000,000.
`is_tax_inclusive`	Yes	boolean	Whether `price` includes tax for modifiers in this group.
`tax_rate`	Yes	number	Tax rate as a decimal (for example `0.15` for 15%). 0–1.
`price`	Yes	number	List price for modifiers in this group. ≥ 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.
`default_quantity`	Yes	number	Pre-selected quantity for modifiers in this group. ≥ 0.
`charge_above_quantity`	No	number	Free selections before charges apply. Optional.
`display_type`	No	string	How modifiers render in the UI: `RADIO`, `CHECKBOX`, or `QUANTITY`. Optional.

Mapping menus to your POS

Match the id field to the menu identifier in your POS or RMS. Use fulfillment_id, store_id, channel_id, brand_id, and menu_id query parameters together to read the menu for a specific selling context.

Use external IDs (fulfillment_id, store_id, channel_id, brand_id) for cross-system mapping. Use *_uid fields when referencing Fire spark resources in other API calls.

Rate limits

GET and PUT /api/integrations/v1/menus share a limit of 30 requests per 10 seconds per merchant, keyed from your access token’s merchant_id. Send one request at a time per merchant — wait for each response before starting the next. Responses include X-RateLimit-Limit and X-RateLimit-Reset. On 429, also read X-RateLimit-Remaining and Retry-After. See Upsert menus — Rate limits.

Error responses

Status	Description
`400`	Invalid scope query parameter.
`401`	Missing or invalid access token.
`403`	Token does not include the `menus:read` scope.
`429`	Rate limit exceeded — wait for `Retry-After` / `X-RateLimit-Reset` before retrying.

API Documentation

Endpoints

Guides

Resources

Query parameters

Request

Response

Menu object

Mapping menus to your POS

Rate limits

Error responses

​Query parameters

​Request

​Response

​Menu object

​Mapping menus to your POS

​Rate limits

​Error responses

Query parameters

Request

Response

Menu object

Mapping menus to your POS

Rate limits

Error responses