> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List menus
> Read composed menu definitions for POS and RMS mapping.
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](/docs/integrations-api/menus/put).
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](/docs/storefront-api/menus/get) when you need the customer-facing menu for the current order time.
Requires an access token with the `menus:read` scope. See
[Token](/docs/integrations-api/oauth/token/post) 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](/docs/integrations-api/fulfillment/get). |
| `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](/docs/integrations-api/menus/put). Use `menu_id` when you need to narrow further within that scope.
## Request
```bash theme={null}
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.
```json Success theme={null}
{
"data": [
{
"id": "lunch-delivery",
"uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"organization_id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
"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" },
"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"
}
]
}
```
## Menu object
| 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. |
| `organization_id` | string (UUID) | Organization that owns the merchant. |
| `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. |
| `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). |
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`. |
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`, `UNAVAILABLE`, 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. |
```json Example product theme={null}
{
"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": {}
}
```
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. |
| `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`, `UNAVAILABLE`, 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. |
```json Example category theme={null}
{
"id": "mains",
"name": { "en_us": "Mains" },
"description": { "en_us": "Burgers and sandwiches" },
"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": {}
}
```
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 `{}`. |
```json Example modifier group theme={null}
{
"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": {}
}
```
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. |
| `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 `[]`. |
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 **10 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](/docs/integrations-api/menus/put#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. |
## OpenAPI
````yaml integrations-api/openapi.json GET /menus
openapi: 3.0.1
info:
title: Fire spark Integrations API
description: POS and RMS integration endpoints for Fire spark.
version: 1.0.0
servers:
- url: https://firespark.cloud/api/integrations/v1
security:
- bearerAuth: []
paths:
/menus:
get:
summary: List menus
parameters:
- in: query
name: fulfillment_id
required: false
schema:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: >-
External fulfillment identifier. When set, filters to that
fulfillment type.
- in: query
name: store_id
required: false
schema:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: >-
External store identifier. Omit or pass _ for merchant-wide default
(null store_id).
- in: query
name: channel_id
required: false
schema:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: >-
External channel identifier. Omit or pass _ for all channels (null
channel_id).
- in: query
name: brand_id
required: false
schema:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: >-
External brand identifier. Alphanumeric characters, _, and - only.
1–64 characters.
- in: query
name: menu_id
required: false
schema:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: External menu identifier. When set, filters to one composed menu.
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/MenuDefinitionUpsert'
components:
schemas:
MenuDefinitionUpsert:
type: object
required:
- id
- name
- status
properties:
id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
name:
$ref: '#/components/schemas/MultiLanguageText'
description:
allOf:
- $ref: '#/components/schemas/MultiLanguageText'
nullable: true
schedules:
type: array
items:
type: object
nullable: true
metadata:
type: object
additionalProperties: true
cms_template_id:
type: string
format: uuid
nullable: true
category_ids:
type: array
items:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
status:
type: string
enum:
- ACTIVE
- INACTIVE
MultiLanguageText:
type: object
additionalProperties:
type: string
example:
en_us: Example
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````