Migrate to Menu v3

Move an existing integration from the legacy menu endpoints to the Menu Management API: what changes, how concepts and endpoints map, and the steps to migrate.

Migrate to Menu v3

📘

Companion guide

This guide is a companion to Create your first menu, Publish your first menu and Menu Structure v3.0. Those pages explain the v3 API. This page explains how to move an existing integration from the legacy menu endpoints to it.

1. What's changing

Flipdish is moving every menu to a new menu platform (menu v3). Once a merchant's menu has been moved, it is managed and published from menu v3 only. Changes sent to the legacy menu endpoints (/api/v1.0/menus/... and /api/v1.0/{appId}/menus) will no longer reach that merchant's ordering channels.

What you get in return:

  • Revisions: every save is a snapshot you can audit or roll back to.
  • Controlled go-live: nothing goes live until you publish, and you choose which sales channels it goes to.
  • Proper snoozing: temporarily hide items by property and sales channel without editing the menu.
  • Your own IDs on the menu: set externalId on items to keep them linked to your system.

2. Do you need to act?

You need to act if your integration creates, updates, deletes or reads menus, sections, items, option sets or option set items through the legacy menu API, or sets item metadata, tax rates, images, nutrition or availability through it.

3. Timeline

⏳

31st March 2027

4. What's different

TopicLegacy menu APIMenu v3 (Menu Management API)
GranularityOne endpoint per entity (section, item, option set, option set item)Whole-menu document. GET the menu, change it, PUT the full document back
Going liveEvery write is live immediatelySaving creates a revision. Nothing is live until the menu is assigned to a sales channel and a revision is published to it
ConsistencySynchronousPublishing is asynchronous. Changes reach channels shortly after the publish call
IDsIntegers (menu, section, item, option set IDs)Server-generated UUIDs. Omit id for new entities, round-trip it for existing ones. Use externalId for your own IDs
Scope in URLsappId (e.g. fd1234) or bare menuIdorgId (e.g. org123): /menuManagement/orgs/{orgId}/...
AuthLegacy bearer tokenOAuth2 client credentials with Org Management and Menu Management access; User-Agent header required
Prices and taxPrice on entity, tax rate via separate endpointspricingProfiles per price band, with price and tax for each dispatch type
Temporary unavailabilityBulk show/hide, or toggling itemsSnooze and un-snooze endpoints (no publish needed)
Delete menuHard deleteArchive

5. Concept mapping

LegacyMenu v3
App (appId)Org (orgId)
StoreProperty, with one or more sales channels
MenuSectionCategory
MenuSectionItemItem (CategoryItem)
MenuItemOptionSetModifier (group), linked to items via ModifierMember
MenuItemOptionSetItemItem inside a Modifier (modifier option)
Price and tax ratePricingProfile per price band: price, tax and taxable flag for collection, delivery, dine-in and takeaway
Section availability timesAvailabilityOverride on Category or Item
Menu zonesCategoryGroup
Item and option imagesimageUrl on Category and Item
Your own item IDsexternalId on Category and Item
Item metadata per storeposMetadata scoped by sales channel, property or all
Bulk show/hideSnooze / un-snooze

6. Endpoint mapping

Legacy endpointMenu v3 replacement
GET /{appId}/menusGET /menuManagement/orgs/{orgId}/menus/headers or .../menus/published
GET menus/{menuId}GET .../menus/{menuId}/current
POST /{appId}/menus (create menu)POST .../menus, assign to sales channels, then publish
POST menus/{menuId} (update menu)Edit document, PUT .../menus/{menuId}, publish
Section, section item, option set and option set item create / update / deleteEdit the entity in the document, PUT once, publish once
DELETE menus/{menuId}DELETE .../menus/{menuId} (archive)
POST menus/{menuId}/bulkshowhidePOST .../snoozes and POST .../un-snoozes
Section availability endpointsavailabilityOverrides in the document
Tax rate endpoints (.../taxrate)Tax fields in pricingProfiles
POST menus/{menuId}/sectiondisplayordersOrder of arrays in the document
PUT zones/{id}/section/{sectionId}categoryGroups in the document
Image upload (.../image, /{appId}/catalog/images)imageUrl field
Metadata (.../metadata/store/{storeId})Metadata or externalId
Nutrition (.../nutritionv2)Metadata

7. Migration steps

Step 1: Get v3 credentials

Create an OAuth App in the Flipdish portal (My OAuth Apps) with Org Management and Menu Management access. Exchange the OAuth App ID and Secret Key for a token using the client credentials grant, and send a descriptive User-Agent on every request.

curl --request POST \
  --url https://api.flipdish.co/identity/connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=<your_oauth_app_id> \
  --data client_secret=<your_secret_key> \
  --data scope=api

Step 2: Map your merchants and menus

  • For each merchant, record the orgId, the propertyIds, and the salesChannelIds you publish to (GET /orgManagement/orgs/{orgId}/properties and .../properties/{propertyId}/salesChannels). Org Management responses use orgId, propertyId and salesChannelId, not id.
  • List the merchant's menus with GET /menuManagement/orgs/{orgId}/menus/headers and record each menuId.
  • Record the merchant's price bands (GET /orgManagement/orgs/{orgId}/priceBands). Every item needs a pricingProfiles entry per price band in use.

Step 3: Re-link your own IDs

Don't rely on legacy integer IDs. Instead, set externalId on categories and items to your own POS or catalogue ID, and store the server-generated ids alongside. Do a full sync once after migration to populate them.

Step 4: Replace your write calls with "batch, save, publish"

This is the biggest change. Instead of one call per entity, apply every change from a sync run to the menu document, then save and publish once.

1. GET  /menuManagement/orgs/{orgId}/menus/{menuId}/current      -> full menu (under "data") + revisionId
2. Apply ALL pending changes to the document locally
3. PUT  /menuManagement/orgs/{orgId}/menus/{menuId}              -> returns the new revisionId
4. GET  /menuManagement/orgs/{orgId}/menus/{menuId}/revisions/{revisionId}/publishCheck
5. POST /menuManagement/orgs/{orgId}/menus/{menuId}/revisions/{revisionId}/publish
        body: { "selectedSalesChannelIds": ["sc123", "sc456"] }

Rules for the document:

  • Responses wrap the menu in a data envelope. Unwrap it before editing and sending it back.
  • Send every existing category and item back with its id unchanged. Changing or dropping an id creates a new entity.
  • Omit id on new entities. The server generates one and returns it in the response; store it for next time.
  • Keep cross-references valid (ModifierMember.parentModifierId, CategoryGroup.categoryIds).
  • Fill in every dispatch-type price and tax field in pricingProfiles for each price band.
  • Pass through fields you don't manage rather than regenerating them, so merchant edits are not overwritten.

Step 5: Creating a menu and making it live

Creating a menu and publishing it are separate from linking it to a sales channel. To take a new menu live:

  1. POST /menuManagement/orgs/{orgId}/menus with the full body (categories, modifiers, categoryGroups, no id fields). Capture data.id and data.revisionId.
  2. Assign the menu to each sales channel with updateSalesChannelById. This is a full replace, so GET the channel first, merge in menuId, and POST it back.
  3. Run publishCheck, then publish the revision to those sales channels.
# Assign menu to a sales channel (full update: carry over existing fields)
curl -s "https://api.flipdish.co/orgManagement/orgs/$ORG_ID/properties/$PROPERTY_ID/salesChannels/$SC_ID" \
  -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" \
  | jq --arg menuId "$MENU_ID" '.data | { name, priceBandId, phoneNumber, usePropertyPhoneNumber, menuId: $menuId } | with_entries(select(.value != null))' \
  > channel-update.json

curl -s -X POST "https://api.flipdish.co/orgManagement/orgs/$ORG_ID/properties/$PROPERTY_ID/salesChannels/$SC_ID" \
  -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" -H 'Content-Type: application/json' \
  --data @channel-update.json
💡

If you skip the assignment, publish fails with "No storefronts are associated with this menu". "Storefront" in that message means sales channel.

If your integration creates a new menu on every sync and deletes the old one, plan to switch to updating one long-lived menu with PUT. Each DELETE is now an archive, so create-and-delete cycles leave archived menus behind, and each new menu must be reassigned to every sales channel.

Step 6: Replace show/hide with snoozing

For "out of stock" or "kitchen closed for this item", use POST .../menus/{menuId}/snoozes and POST .../menus/{menuId}/un-snoozes, scoped by property. No publish needed. For permanent removal, edit the document and publish. For recurring schedules, use availabilityOverrides.

8. Getting help

For any questions, reach out to [email protected]. We're happy to help get you sorted before the deadline.