Skip to main content

Read, send, and upsert menus

Read menus stored in Otter, replace a store's complete menu snapshot, return the current menu when Otter requests it, and track asynchronous menu jobs to completion.

POST /v1/menus replaces the complete menu snapshot. It is not a partial update. Include every entity that should remain.

Before you begin​

  • Application credentials and store linked
  • Stable ids for categories, items, and modifiers (your system ids — Otter reuses them)
  • A webhook endpoint configured for menu events

Steps​

Read, Send, and Upsert Menus Flow

Replace the complete menu​

  1. Optionally read all menus for the store with GET /v1/menus.
  2. Build the complete desired menu state. Customer-menu entities omitted from the relationship graph are deleted. Entries present only in top-level maps but unreachable from menus, categories, or items are not processed.
  3. Replace the menu with POST /v1/menus. The 202 Accepted response includes a pending job id. It confirms workflow submission, not that menus or photos were persisted.
  4. Poll GET /v1/menus/jobs/{jobId} until status is SUCCESS or FAILED.

For overnight hours, set the end time earlier than the start time on the day service begins. For example, Monday 20:00 to 02:00 means Monday evening through Tuesday at 02:00. Do not split it into two API intervals.

Return the current menu when requested​

  1. Receive the Send menu (menus.send_menu) webhook and acknowledge it with a 2xx response.
  2. Return the store's current menu through POST /v1/menus/current. Send the webhook's event ID in the X-Event-Id header.
  3. Poll GET /v1/menus/jobs/{jobId} for the associated menu job until its status is SUCCESS or FAILED.

Verify​

  1. Upsert a test menu and wait for SUCCESS.
  2. Send the same complete payload again and verify the resulting menu is unchanged. Each submission still creates a new workflow; this is not an idempotency guarantee.
  3. Remove one customer item from the complete payload, upsert again, and verify that item is deleted.
  4. Trigger a Send menu event. Confirm that your webhook and menu callback return successful 2xx responses, then verify that the associated menu job reaches SUCCESS.

Common failures​

SymptomLikely causeFix
Send menu event not receivedWebhook destination is not configured for the eventCheck the webhook configuration for your app
Callback returns 400 or 404Missing or incorrect store or event IDUse the store ID and top-level event ID from the webhook
Callback returns 422Menu payload does not match the expected schemaCompare the payload with the menu send callback
Job remains PENDINGThe menu is still being processed or the service is backloggedContinue polling with backoff and check rate limits
Job reaches FAILEDThe asynchronous menu operation could not be completedInspect the job error and correct the menu data before retrying
Existing entities disappearThe replacement payload omitted themRead the current menu, merge intended changes, and send the complete desired state
Ambiguous response after submissionThe workflow may already have startedInspect the menu and job status before resubmitting

Inbound menu and photo limits are not represented by the publish-target capabilities in the Integration Registry. Confirm applicable payload, entity, photo, and template-menu restrictions during onboarding.

Next​