Sync menu

POST /v1/sync

Upserts categories, ingredients and products (with their modifier groups) in one request. Every item is matched by your externalId: unknown ids are created, known ids are updated, unchanged items are skipped. Repeating the same request is safe (idempotent).

Sections are processed in order categories → ingredients → products inside a single database transaction, so products can reference categories and ingredients created earlier in the same request.

Sync updates the draft menu. Guests see changes only after POST /v1/publish.

Request body#

All three arrays are optional — send any subset. Per-request caps: 200 categories, 200 ingredients, 500 products (a larger array is a 400 validation error; bodies over 5 MB are rejected). Per product: ≤ 20 modifier groups (≤ 50 options each) and ≤ 100 ingredient references.

An empty body is not an error: it returns success: true with a warning and changes nothing.

categories[]#

ingredients[]#

products[]#

Inline translations — a full multilingual menu in ONE sync#

Every sync entity (categories, ingredients, products, and each modifier group) accepts an optional translations map — locale-keyed field maps:

{
  "categories": [
    {
      "externalId": "cat-mains", "name": "Mains",
      "translations": { "uk": { "name": "Основні" }, "de": { "name": "Hauptgerichte" } }
    }
  ],
  "products": [
    {
      "externalId": "prod-margherita", "name": "Margherita", "priceMinor": 24500,
      "translations": { "uk": { "name": "Маргарита", "description": "Томати, моцарела" } },
      "modifierGroups": [
        {
          "name": "Extras", "type": "add_ingredients",
          "options": [{ "ingredientExternalId": "ing-olives" }],
          "translations": { "uk": { "name": "Добавки" } }
        }
      ]
    }
  ]
}

• Allowed fields per entity match the translation routes: products name/description/badgeLabel; categories, ingredients and modifier groups name.
• Merge semantics — omitting translations (or a locale, or a field) on a re-sync preserves what's stored; "" clears a field. Translations and content land in the same transaction.
• Locales must be globally supported AND venue-enabled — errors name the entity (INVALID_LOCALE, LOCALE_NOT_ENABLED, EMPTY_TRANSLATION).
• The response reports translations: { applied: N } (locale-entries written). Dry runs validate translations too, writing nothing.

The full-menu agent flow is now: 1 PATCH /v1/settings (enabledLanguages) → 1 sync (content + all translations) → 1 publish. For incremental fixes after the build, use the bulk translation write.

Single-product updates — PATCH /v1/products/:ref#

For touching one product, prefer the dedicated partial update over a one-item sync:

PATCH /v1/products/:ref

• Same field set as sync products (minus externalId, ingredientExternalIds and modifierGroups — composition/modifier changes stay on sync, whose replace-semantics they need).
• Uniform semantics on every field: omitted = keep, null = clear (nullable fields), value = set — no bulk special cases.
• categoryRef accepts your externalId or the opaque id; null detaches. Unlike sync, an unknown ref is a hard 404 CATEGORY_NOT_FOUND (precise feedback beats a warning for a single-item call).
• Supports optimistic concurrency: the response carries an ETag; send it back as If-Match and a concurrent change fails with 412 STALE_RESOURCE (same pattern as settings).
• Changes affect the draft — publish to go live.

curl -X PATCH https://api.duck-hub.com/v1/products/prod-margherita \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "priceMinor": 26500, "badgeLabel": null }'

const response = await fetch(
  'https://api.duck-hub.com/v1/products/prod-margherita',
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer dk_live_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ priceMinor: 26500, badgeLabel: null }),
  },
)
const product = await response.json() // updated product view

modifierGroups[]#

modifierGroups[].options[]#

Example#

curl -X POST https://api.duck-hub.com/v1/sync \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": [
      { "externalId": "cat-pizza", "name": "Pizza", "sortOrder": 1 }
    ],
    "ingredients": [
      { "externalId": "ing-mozzarella", "name": "Mozzarella" },
      { "externalId": "ing-olives", "name": "Olives" }
    ],
    "products": [
      {
        "externalId": "prod-margherita",
        "name": "Margherita",
        "description": "Tomato, mozzarella, basil",
        "priceMinor": 21500,
        "categoryExternalId": "cat-pizza",
        "ingredientExternalIds": ["ing-mozzarella"],
        "modifierGroups": [
          {
            "name": "Extras",
            "type": "add_ingredients",
            "options": [
              { "ingredientExternalId": "ing-olives", "priceAdjustment": 2500 }
            ]
          }
        ]
      }
    ]
  }'

const response = await fetch('https://api.duck-hub.com/v1/sync', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    categories: [{ externalId: 'cat-pizza', name: 'Pizza', sortOrder: 1 }],
    ingredients: [
      { externalId: 'ing-mozzarella', name: 'Mozzarella' },
      { externalId: 'ing-olives', name: 'Olives' },
    ],
    products: [
      {
        externalId: 'prod-margherita',
        name: 'Margherita',
        description: 'Tomato, mozzarella, basil',
        priceMinor: 21500,
        categoryExternalId: 'cat-pizza',
        ingredientExternalIds: ['ing-mozzarella'],
        modifierGroups: [
          {
            name: 'Extras',
            type: 'add_ingredients',
            options: [
              { ingredientExternalId: 'ing-olives', priceAdjustment: 2500 },
            ],
          },
        ],
      },
    ],
  }),
})
const result = await response.json()

Response#

201 Created. Each section you sent gets its own result block:

{
  "success": true,
  "categories": {
    "created": 1, "updated": 0, "skipped": 0, "errors": [], "warnings": []
  },
  "ingredients": {
    "created": 2, "updated": 0, "skipped": 0, "errors": [], "warnings": []
  },
  "products": {
    "created": 1, "updated": 0, "skipped": 0,
    "errors": [],
    "warnings": []
  },
  "warnings": [],
  "syncedAt": "2026-07-05T12:00:00.000Z"
}

Top-level warnings carries request-wide notes (duplicate externalIds, empty request). Per-section warnings carries item-scoped notes like "Product prod-x: category 'cat-y' not found, saved without category".

Dry run#

Append ?dryRun=true to validate a sync without writing anything: the full pipeline runs — validation, plan-limit checks, reference resolution, create/update/skip decisions — and you get the same response shape with "dryRun": true and the counts/warnings the real call would produce. Plan-limit and validation failures return the same errors as a real sync. Use it to iterate cheaply before committing a large sync.

curl -X POST "https://api.duck-hub.com/v1/sync?dryRun=true" \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "products": [ ... ] }'

Errors#

• 400 Validation failed — schema violations, array caps (200/200/500)
• 400 plan limit exceeded — see Plan limits; checked before writing, counting only new items
• 401 — see Authentication

Syncing a previously cleaned-up (soft-deleted) product by its externalId restores it.