Menu sync - Fire spark

Menu sync is how your POS or RMS becomes the source of truth for what customers can order on every connected channel. You push catalog entities once, then Fire spark composes what each surface shows — different assortments by channel, store, fulfillment type, or schedule without maintaining a separate integration per partner.

New to Fire spark?

Read the Integrations API introduction for authentication, webhooks, and the full integration model.

Your operational system owns items, prices, and availability. Fire spark sits in the middle and publishes composed menus to owned channels and aggregators. When a customer orders, line item id values from the composed menu appear on the order payload and on the POS ticket after order.injected. Keep external product ids stable across menu sync and order injection.

Prerequisites

Create stores, channels, and fulfillment types in the Fire spark dashboard before your first menu upsert. Each resource uses the same external id you use in your POS or RMS.

Obtain an access token

Authenticate with OAuth 2.0 client credentials. Menu endpoints require menus:read and menus:write. See Token.

Confirm fulfillment options

Verify delivery, pickup, dine-in, and any custom fulfillment types exist in the dashboard. See List fulfillment.

Confirm stores

Verify each merchant location and its external ids. Stores carry channel availability and local rules. See List stores.

Confirm channels

Verify the channels configured for the merchant — app, web, kiosk, aggregators, and others. See List channels.

Menu upserts return 409 when referenced fulfillment_id, store_id, channel_id, or brand_id values do not exist for the merchant. Create stores, channels, fulfillment, and brands in the dashboard before the first sync.

A composed menu is the catalog a customer sees for one selling context. Fire spark scopes each menu to a store, channel, and fulfillment triple. You can add schedules so the same triple shows different categories at breakfast vs lunch.

Dimension	What you control	Example
Store	Location-specific assortment and pricing	Airport store excludes dine-in-only items
Channel	Surface-specific catalog	Full menu on app; delivery-friendly subset on Uber Eats
Fulfillment	Mode-specific items	Delivery menu hides large-format drinks unavailable for courier
Schedule	Time-of-day or day-of-week menus	Breakfast categories until 11:00; dinner menu after 17:00

You update the POS once. Your integration decides how many composed menus to push and which categories and products each menu includes.

For background on why menus are composed per context, see Menus. For category-level availability by channel and store, see Categories.

Catalog building blocks

Every composed menu is built from four entity types you send in the same request.

Entity	Role	Learn more
Product	Sellable item — burger, combo base, drink, modifier option	Products
Category	Browse section that lists product ids	Categories
Modifier group	Choice rules attached to a product	Products — modifier groups
Menu	Named catalog for one store + channel + fulfillment, with optional schedules	This guide

Products

A product is anything that can appear on a ticket: a standalone burger, a combo, or a modifier option such as “Cola.” Send products in the top-level products array on Upsert menus. Each product needs a stable external id — the same value your kitchen expects on injected orders.

Field	When it matters
`pricing.price`	List price for this menu context
`pricing.modifier_group_ids`	Modifier groups the customer must or can configure
`bundled_items`	Products included in a combo by default
`availability.status`	`AVAILABLE`, `UNAVAILABLE`, or `OUT_OF_STOCK`
`availability.out_of_stock_until`	Temporary 86 from your POS

Step	What to send
1	Declare all categories in `categories[]` — roots and children share the same array
2	In the parent category, list children with `items: [{ "type": "CATEGORY", "id": "burgers" }, ...]`
3	In leaf categories, list products with `items: [{ "type": "PRODUCT", "id": "..." }]`
4	In the menu, reference only the root in `menus[].category_ids` — Fire spark resolves the tree from there

Level	Field	What it orders
Menu sections	`menus[].category_ids`	Root categories visible on the menu
Subcategories	`parent.items` with `type: "CATEGORY"`	Subcategories inside the parent
Products	`category.items` with `type: "PRODUCT"`	Products inside the category

Modifier groups and modifiers

Customization is modeled in two layers:

Layer	What it is	Example
Modifier group	The question and its rules (min/max selections, display type)	“Choose a drink” — required, pick exactly 1
Modifier	One selectable answer inside the group	Cola, Sprite, still water

Modifiers are products. Each entry in a group’s modifier_ids array is the external id of another product in the same payload. That means:

A drink sold standalone and as a combo modifier shares one product record.
When you 86 still water in the POS, set availability.status to OUT_OF_STOCK on that product — the modifier disappears from every group that references it.
Kitchen tickets use real product ids, not free-text notes.

Attach groups to a parent product through pricing.modifier_group_ids. Set selection rules on the group:

Group field	Purpose
`minimum_quantity`	Required selections (for example 1 drink on a combo)
`maximum_quantity`	Cap for optional add-ons
`display_type`	`LIST` or `GRID` in customer UI
`charge_above_quantity`	Free selections before additional charges apply

Per-modifier price, default quantity, display type (RADIO, CHECKBOX, QUANTITY), and charge rules live on the modifier product under pricing.modifiers — one entry per modifier_group_id where that product appears as an option. See Modifier display types for the quantity rules that determine each display_type, validation errors, and examples.

Use the same external ids in menu sync, order line items, and POS mapping. When order.injected fires, modifier lines reference these ids in the order payload.

Defaults first, override where needed

Omitted scope means any (__ANY__). You can publish one baseline menu and add narrower upserts only where your operation differs — instead of one API call per store, channel, and schedule combination.

What you omit	What Fire spark assumes
`store_id` query parameter	Menu applies to any store
`channel_id` query parameter	Menu applies to any channel
`fulfillment_id` query parameter	Menu applies to any fulfillment type
`schedules: null` on the menu	Available 24 hours, every day

Add fulfillment_id, store_id, channel_id, brand_id, or schedule entries only when a specific context needs something different from that baseline. More specific upserts apply to that context alone; they do not remove the default for contexts you left untouched.

A merchant-wide default is optional but recommended when the customer has not chosen a store or fulfillment type yet — for example pickup vs delivery while browsing before checkout. Fire spark does not require a baseline upsert before scoped overrides.

Suggested sync order (when you use a baseline):

Push a merchant-wide default — PUT /menus with no query parameters and set "schedules": null. Send your full product catalog.
Push overrides — repeat the upsert with ?store_id=…, ?channel_id=…, ?fulfillment_id=…, or a schedules array only where the catalog, pricing, or hours diverge from the baseline.

You can also sync only scoped menus if every selling context you support is already known.

Sync workflow

Choose the selling context

Decide whether this upsert is the merchant-wide default (omit scope query parameters) or a targeted override for one store, channel, brand, and/or fulfillment type. See Upsert menus for query parameters.

Build the payload

Send shared catalog entities (products, categories, modifier_groups) plus up to 10 menus entries in one request. Each menu object references category_ids and a fulfillment_id.

Upsert the menu

Call PUT /menus for the baseline, or add ?store_id=… and/or ?channel_id=… for overrides. Use "style": "DEFAULT" for owned channels, or "style": "UBER_EATS" for Uber Eats Menu API v2 shape. See Upsert menus.

Verify the result

Read back composed menus with List menus. Pass the same store_id and channel_id you used on the upsert. Confirm ids match your POS mapping.

Push incremental changes

For single-item updates — price changes, 86s, channel-specific overrides — call Update product instead of resending the full menu.

Multiple channels, stores, and fulfillment modes

Each composed menu is keyed by context:

fulfillment_id + store_id + channel_id + brand_id + menu.id

When fulfillment_id, store_id, channel_id, or brand_id is omitted, that dimension is all. Use that to your advantage: one baseline upsert with the full catalog, then overrides only where needed.

Scenario	Approach
Same catalog everywhere	Single `PUT /menus` with no query params; `schedules: null` for 24/7
One aggregator needs a subset	Baseline (optional), then `PUT /menus?channel_id=uber-eats` with different `category_ids` — or sync that channel only
One store has regional items	Baseline (optional), then `PUT /menus?store_id=airport` — or sync that store only
Delivery vs pickup	`PUT /menus?fulfillment_id=delivery` vs `?fulfillment_id=pickup` — or separate menu ids per fulfillment when assortments differ
Brand with multiple labels	Pass `brand_id` query parameter to scope upserts per brand

Item-level overrides across contexts

When one product needs different pricing or availability per channel, store, or fulfillment type without replacing whole menus, call Update product with ?store_id=…, ?channel_id=…, ?fulfillment_id=…, and/or ?menu_id=… when several menus share the same scope. The body uses the same menu product shape as Upsert menus — top-level pricing and availability, not a nested channels object. This matches how commercial teams think: push a baseline product once, then send a scoped update so Cola is $0 on the combo in the app at downtown, while the default catalog keeps a different price elsewhere. Edits made from the dashboard or using our sync API persist across normal upserts. To override these changes, send x-force: true on Upsert menus. To stage a sync without publishing yet, send x-publish: false and publish from the dashboard when ready.

Schedules

Schedules restrict when a menu or individual entity is orderable.

Level	Field	Format
Menu	`menus[].schedules`	Weekly array (`monday`–`sunday`); each period may include `start_time` / `end_time`, optional `closed` (default `false`), and optional `start_date` / `end_date`
Product / category	`availability.schedules`	Same shape; applies within the composed menu
Product override	`availability.schedules` on Update product with `?store_id` / `?channel_id` / `?fulfillment_id` / `?menu_id`	Per-context hours for one selling context or one composed menu

Use null or omit schedules when the menu is available around the clock — Fire spark treats that as 24 hours, every day. Set a schedules array only when orderability is limited to specific days or time windows. When you send a schedules array, Fire spark validates the full weekly shape:

Rule	Requirement
Week coverage	Exactly 7 entries — one per weekday from `monday` through `sunday`
Unique days	Each `day_of_week` appears once
Periods per day	At most 10 periods
Period fields	Open periods require `start_time` and `end_time`. Optional `closed` defaults to `false`. `start_date` / `end_date` are nullable (both set or both `null`)
No overlap	Null-date periods on the same day must not overlap in time. Specific-dated closed and open periods must not share a date range. Null-date + specific-dated periods may coexist

Times in start_time and end_time use ISO time strings (for example 11:00:00). Set closed: true when the period is a closed window (start_time / end_time may be omitted). Use null dates for the always-on fallback; set start_date / end_date for a more specific window. An empty periods array means closed all day. Multiple menus in the same sync may share overlapping schedule windows. Get menu returns every composed menu whose schedule matches the current time in data. When none are in schedule, it returns the menu or menus whose next window starts soonest. Menus with schedules: null are always considered active. Common patterns:

Always-on default — Omit schedules (null) on the baseline menu; add scheduled overrides only for dayparts that differ.
Daypart menus — Separate menu ids for breakfast and lunch on the same store + channel + fulfillment, each with its own schedule and category_ids.
Closed windows — Keep open hours on a day and add a closed: true period (optionally with start_date / end_date) for a holiday or maintenance block.
Seasonal categories — Keep the menu always active; schedule the category or product availability instead.
Temporary 86 — Prefer availability.status: OUT_OF_STOCK with out_of_stock_until for item-level pauses without rebuilding schedules.

Validation rules

Fire spark validates the full Upsert menus payload before queuing a sync. These rules apply to the DEFAULT style.

Products

Field	Rule
`products`	At least 1 entry. At most 1000.
`id`, `name`, `pricing`, `availability`	Required on each product
`status`	Not accepted on menu sync products. Use `availability.status` instead.
`availability.status`	`AVAILABLE`, `UNAVAILABLE`, or `OUT_OF_STOCK`
`availability.schedules`	Same weekly rules as menu schedules when provided. Omit or set `null` for no restriction.
`availability.out_of_stock_until`	Optional ISO 8601 datetime
`labels`	Optional. At most 64 strings (1–128 characters each). Defaults to `[]`.
`tags`	Optional. Object of boolean, string, or number values. Defaults to `{}`.

Field	Rule
`categories`	At least 1 entry. At most 100.
`id`, `name`, `items`, `availability`	Required on each category
`status`	Not accepted on menu sync categories. Use `availability.status` instead.
`items`	At least 1 entry. At most 1000. Each entry requires `type` (`CATEGORY` or `PRODUCT`) and `id`. Array order is display order. No duplicate ids within the same category.
`availability.status`	`ACTIVE`, `INACTIVE`, or `HIDDEN`
`availability.schedules`	Same weekly rules as menu schedules when provided. Omit or set `null` for no restriction.
`availability.inactive_until`	Optional ISO 8601 datetime
`labels`	Optional. At most 64 strings (1–128 characters each). Defaults to `[]`.
`tags`	Optional. Object of boolean, string, or number values. Defaults to `{}`.

Rule	Requirement
References	Each `items[].id` must exist in `products[]` (when `type` is `PRODUCT`) or `categories[]` (when `type` is `CATEGORY`)
Reachability	Every category must appear in `menus[].category_ids` or be referenced as a child in another category’s `items`
Depth	At most 3 levels from each root in `category_ids`, counting the root as level 1
Cycles	A category cannot be an ancestor of itself

Field	Rule
`menus`	At least 1 entry. At most 10.
`id`, `name`, `category_ids`, `status`	Required on each menu
`category_ids`	At least 1 category id. At most 100. Root categories only. Array order is display order. No duplicate ids.
`status`	`ACTIVE` or `INACTIVE`
`schedules`	Optional. `null` or omitted for 24/7. When set, must pass the weekly schedule rules above.

Modifier groups

Field	Rule
`modifier_groups`	Optional. At most 1000 when provided.
`modifier_ids`	At least 2 entries per group

Recommendations

Field	Rule
`recommendations`	Optional. At most 1000 when provided. Defaults to `[]`.
`id`, `title`, `type`, `target_product_id`	Required on each recommendation
`type`	`UPSELL`, `CROSS_SELL`, or `DOWNSELL`
`target_product_id`	Must reference a product `id` in `products`
`pricing.recommendations_ids`	Optional on each product. Each id must exist in `recommendations`
`pricing.recommendations`	Optional on each product. Each `recommendation_id` must exist in `recommendations`. Duplicate ids are rejected per product
`pricing.recommendations[].default_quantity`	Optional. Defaults to `0`. Independent from `pricing.modifiers[].default_quantity`

When a sync defines multiple menus, Fire spark composes each menu from the shared catalog and keeps only recommendations whose target_product_id is reachable in that menu — the same composition rules as products and modifier_groups.

Labels and tags

Products and categories accept optional labels and tags. Omit either field on existing syncs — Fire spark defaults to [] and {} and does not reject payloads that leave them out.

Field	Shape	Use
`labels`	`string[]`	Filters and quick selection in the Dashboard.
`tags`	`{ [key: string]: boolean \| string \| number }`	Advanced cases such as custom rules. See Custom rules.

{
  "id": "burger-classic",
  "labels": ["featured", "lunch"],
  "tags": { "promo_eligible": true, "kitchen_station": "grill" }
}

Category availability uses ACTIVE, INACTIVE, and HIDDEN — not the product values AVAILABLE, UNAVAILABLE, and OUT_OF_STOCK. Categories also use inactive_until, not out_of_stock_until.

Sync styles

Upsert menus accepts a discriminated union on style:

DEFAULT
UBER_EATS

Fire spark native format for owned channels (app, web, kiosk, call center). Use field names products, categories, modifier_groups, and localized name objects keyed by locale (for example en_us).Best when you control the customer UI through the Storefront API or a custom front end.

Uber Eats Menu API v2 payload. Products and modifiers share the items array; prices are integer cents in price_info.price.Best when pushing directly to an Uber Eats aggregator channel without mapping fields yourself. See Uber’s example menu payloads for nested modifiers and bundled items.

Full sync vs incremental updates

Method	Endpoint	When to use
Full menu upsert	Upsert menus	Initial load, structural changes (new categories, modifier groups), or recomposing `category_ids`
Single product	Update product	Price change, 86, or per-channel override on one item
Read back	List menus	Reconciliation and mapping verification for a store and channel (`?store_id` + `?channel_id`)

Menu id values are immutable after creation. Send the same external menu id on every sync for a given selling context.

Map ids back to your POS

Fire spark field	Map to
`products[].id`	POS item / PLU / SKU
`categories[].id`	POS menu section or category code
`menus[].id`	POS menu version or daypart identifier
`fulfillment_id`, `store_id`, `channel_id`, `brand_id`	Location, sales surface, and service mode in your RMS

Use external ids for cross-system mapping. Use *_uid fields only when referencing Fire spark resources in other API calls.

Upsert menus

Create or update composed menus

List menus

Read menus for reconciliation

Update product

Push item-level changes

Order webhooks

Receive orders with the same product ids

List stores

Read store external ids before menus

List fulfillment

Read fulfillment external ids before menus

Example payloads

Copy-paste payloads for common menu sync scenarios:

Simple menu

3 products, 1 category, 1 modifier group

Nested categories

Root category with two subcategories

Multi-schedule

2 daypart menus, no modifier groups

Multi-level modifiers

3 nested modifier group levels

Modifier overrides

Price, min, and max overrides

Product schedule

Happy-hour availability on one product

Product recommendations

Combo upsell, side cross-sell, and combo downsell

New to Fire spark?

​Where menu sync sits in the stack

​Prerequisites

​How menu composition works

​Catalog building blocks

​Products

​Categories

​Nested subcategories

​Modifier groups and modifiers

​Defaults first, override where needed

​Sync workflow

​Multiple channels, stores, and fulfillment modes

​Item-level overrides across contexts

​Schedules

​Validation rules

​Products

​Categories

​Menu definitions

​Modifier groups

​Recommendations

​Labels and tags

​Sync styles

​Full sync vs incremental updates

​Map ids back to your POS

​Related endpoints

Upsert menus

List menus

Update product

Order webhooks

List stores

List fulfillment

​Example payloads

Simple menu

Nested categories

Multi-schedule

Multi-level modifiers

Modifier overrides

Product schedule

Product recommendations

Where menu sync sits in the stack

Prerequisites

How menu composition works

Catalog building blocks

Products

Categories

Nested subcategories

Modifier groups and modifiers

Defaults first, override where needed

Sync workflow

Multiple channels, stores, and fulfillment modes

Item-level overrides across contexts

Schedules

Validation rules

Products

Categories

Menu definitions

Modifier groups

Recommendations

Labels and tags

Sync styles

Full sync vs incremental updates

Map ids back to your POS

Related endpoints

Example payloads