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 guideThis 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
externalIdon 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
| Topic | Legacy menu API | Menu v3 (Menu Management API) |
|---|---|---|
| Granularity | One endpoint per entity (section, item, option set, option set item) | Whole-menu document. GET the menu, change it, PUT the full document back |
| Going live | Every write is live immediately | Saving creates a revision. Nothing is live until the menu is assigned to a sales channel and a revision is published to it |
| Consistency | Synchronous | Publishing is asynchronous. Changes reach channels shortly after the publish call |
| IDs | Integers (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 URLs | appId (e.g. fd1234) or bare menuId | orgId (e.g. org123): /menuManagement/orgs/{orgId}/... |
| Auth | Legacy bearer token | OAuth2 client credentials with Org Management and Menu Management access; User-Agent header required |
| Prices and tax | Price on entity, tax rate via separate endpoints | pricingProfiles per price band, with price and tax for each dispatch type |
| Temporary unavailability | Bulk show/hide, or toggling items | Snooze and un-snooze endpoints (no publish needed) |
| Delete menu | Hard delete | Archive |
5. Concept mapping
| Legacy | Menu v3 |
|---|---|
App (appId) | Org (orgId) |
| Store | Property, with one or more sales channels |
| MenuSection | Category |
| MenuSectionItem | Item (CategoryItem) |
| MenuItemOptionSet | Modifier (group), linked to items via ModifierMember |
| MenuItemOptionSetItem | Item inside a Modifier (modifier option) |
| Price and tax rate | PricingProfile per price band: price, tax and taxable flag for collection, delivery, dine-in and takeaway |
| Section availability times | AvailabilityOverride on Category or Item |
| Menu zones | CategoryGroup |
| Item and option images | imageUrl on Category and Item |
| Your own item IDs | externalId on Category and Item |
| Item metadata per store | posMetadata scoped by sales channel, property or all |
| Bulk show/hide | Snooze / un-snooze |
6. Endpoint mapping
| Legacy endpoint | Menu v3 replacement |
|---|---|
GET /{appId}/menus | GET /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 / delete | Edit the entity in the document, PUT once, publish once |
DELETE menus/{menuId} | DELETE .../menus/{menuId} (archive) |
POST menus/{menuId}/bulkshowhide | POST .../snoozes and POST .../un-snoozes |
| Section availability endpoints | availabilityOverrides in the document |
Tax rate endpoints (.../taxrate) | Tax fields in pricingProfiles |
POST menus/{menuId}/sectiondisplayorders | Order 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=apiStep 2: Map your merchants and menus
- For each merchant, record the
orgId, thepropertyIds, and thesalesChannelIds you publish to (GET /orgManagement/orgs/{orgId}/propertiesand.../properties/{propertyId}/salesChannels). Org Management responses useorgId,propertyIdandsalesChannelId, notid. - List the merchant's menus with
GET /menuManagement/orgs/{orgId}/menus/headersand record eachmenuId. - Record the merchant's price bands (
GET /orgManagement/orgs/{orgId}/priceBands). Every item needs apricingProfilesentry 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
dataenvelope. Unwrap it before editing and sending it back. - Send every existing category and item back with its
idunchanged. Changing or dropping anidcreates a new entity. - Omit
idon 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
pricingProfilesfor 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:
POST /menuManagement/orgs/{orgId}/menuswith the full body (categories,modifiers,categoryGroups, noidfields). Capturedata.idanddata.revisionId.- Assign the menu to each sales channel with
updateSalesChannelById. This is a full replace, soGETthe channel first, merge inmenuId, andPOSTit back. - 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.
Updated about 1 hour ago

