Upsert menús

curl --request PUT \
  --url 'https://firespark.cloud/api/integrations/v1/menus?fulfillment_id=delivery&store_id=centro&channel_id=app&brand_id=0001' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-release-id: 2026-07-03-baseline" \
  -d '{
    "style": "DEFAULT",
    "products": [
      {
        "id": "hamburguesa-clasica",
        "name": { "en_us": "Hamburguesa clásica" },
        "description": { "en_us": "Carne Angus con lechuga y tomate." },
        "image_url": "https://cdn.example.com/hamburguesa-clasica.jpg",
        "bundled_items": [],
        "pricing": {
          "minimum_quantity": 1,
          "maximum_quantity": 10,
          "is_tax_inclusive": true,
          "tax_rate": 0.15,
          "price": 12.99,
          "anchor_price": 14.99,
          "anchor_price_percentage": 0.13,
          "modifiers": [],
          "modifier_group_ids": ["elige-bebida"]
        },
        "availability": {
          "status": "AVAILABLE",
          "schedules": null,
          "out_of_stock_until": null
        },
        "metadata": {}
      },
      {
        "id": "refresco",
        "name": { "en_us": "Refresco" },
        "description": null,
        "image_url": null,
        "bundled_items": [],
        "pricing": {
          "minimum_quantity": 0,
          "maximum_quantity": 1,
          "is_tax_inclusive": true,
          "tax_rate": 0.15,
          "price": 0,
          "anchor_price": 0,
          "anchor_price_percentage": 0,
          "modifiers": [],
          "modifier_group_ids": []
        },
        "availability": {
          "status": "AVAILABLE",
          "schedules": null,
          "out_of_stock_until": null
        },
        "metadata": {}
      },
      {
        "id": "cola",
        "name": { "en_us": "Cola" },
        "description": null,
        "image_url": null,
        "bundled_items": [],
        "pricing": {
          "minimum_quantity": 0,
          "maximum_quantity": 1,
          "is_tax_inclusive": true,
          "tax_rate": 0.15,
          "price": 0,
          "anchor_price": 0,
          "anchor_price_percentage": 0,
          "modifiers": [],
          "modifier_group_ids": []
        },
        "availability": {
          "status": "AVAILABLE",
          "schedules": null,
          "out_of_stock_until": null
        },
        "metadata": {}
      }
    ],
    "categories": [
      {
        "id": "principales",
        "name": { "en_us": "Platos fuertes" },
        "description": { "en_us": "Hamburguesas y sándwiches" },
        "image_url": "https://cdn.example.com/mains.jpg",
        "items": [{ "type": "PRODUCT", "id": "hamburguesa-clasica" }],
        "availability": {
          "status": "ACTIVE",
          "schedules": null,
          "inactive_until": null
        },
        "metadata": {}
      }
    ],
    "modifier_groups": [
      {
        "id": "elige-bebida",
        "title": { "en_us": "Elige una bebida" },
        "description": null,
        "display_type": "LIST",
        "modifier_ids": ["cola", "refresco"],
        "minimum_quantity": 0,
        "maximum_quantity": 1,
        "charge_above_quantity": null,
        "metadata": {}
      }
    ],
    "menus": [
      {
        "id": "almuerzo-delivery",
        "name": { "en_us": "Menú almuerzo delivery" },
        "description": { "en_us": "Ítems de almuerzo entre semana para delivery" },
        "schedules": null,
        "metadata": {},
        "category_ids": ["principales"],
        "status": "ACTIVE"
      }
    ]
  }'

curl --request PUT \
  --url 'https://firespark.cloud/api/integrations/v1/menus?fulfillment_id=delivery&store_id=centro&channel_id=uber-eats&brand_id=0001' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-release-id: 2026-07-03-baseline" \
  -d '{
    "style": "UBER_EATS",
        "display_options": {
          "disable_item_instructions": true
        },
        "items": [
          {
            "id": "Coffee",
            "title": { "translations": { "en_us": "Coffee" } },
            "description": { "translations": { "en_us": "Deliciously roasted beans" } },
            "modifier_group_ids": { "ids": ["Add-milk"] },
            "price_info": { "price": 300 },
            "tax_info": { "tax_rate": 8 },
            "quantity_info": {}
          },
          {
            "id": "Milk",
            "title": { "translations": { "en_us": "Milk" } },
            "quantity_info": {
              "overrides": [
                {
                  "context_type": "MODIFIER_GROUP",
                  "context_value": "Add-milk",
                  "quantity": { "max_permitted": 1 }
                }
              ]
            },
            "price_info": {
              "price": 0,
              "overrides": [
                {
                  "context_type": "MODIFIER_GROUP",
                  "context_value": "Add-milk",
                  "price": 0
                }
              ]
            },
            "tax_info": { "tax_rate": 8 }
          }
        ],
        "categories": [
          {
            "id": "Drinks",
            "title": { "translations": { "en_us": "Drinks" } },
            "entities": [{ "type": "ITEM", "id": "Coffee" }]
          }
        ],
        "modifier_groups": [
          {
            "id": "Add-milk",
            "title": { "translations": { "en_us": "Add milk" } },
            "modifier_options": [{ "type": "ITEM", "id": "Milk" }],
            "quantity_info": { "quantity": { "max_permitted": 1 } },
            "display_type": null
          }
        ],
        "menus": [
          {
            "id": "All-day",
            "title": { "translations": { "en_us": "All day" } },
            "category_ids": ["Drinks"],
            "service_availability": [
              {
                "day_of_week": "monday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "tuesday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "wednesday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "thursday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "friday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "saturday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "sunday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              }
            ]
          }
        ]
      }'

Crea o actualiza menús compuestos para el comercio autenticado. Envía las entidades del catálogo una sola vez en el nivel superior y referencia hasta 10 definiciones de menú en la misma solicitud. Cada menú en menus se empareja por id. Si no existe un menú con ese id para el comercio, Fire spark lo crea. Si ya existe, Fire spark actualiza los campos editables indicados abajo. Los campos omitidos conservan su valor actual en una actualización. Acota el upsert con parámetros de consulta opcionales. Fire spark resuelve el contexto de organización y comercio desde tu access token.

Requiere un access token con el scope menus:write. Consulta Token para obtener un token.

Los valores de id del menú son inmutables. No puedes cambiar el id de un menú existente mediante este endpoint — envía el mismo id que usas en tu POS o RMS en cada sincronización.

Headers

Header	Requerido	Descripción
`x-release-id`	No	Identificador de release para este sync. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. Si se omite, Fire spark genera un valor como `v2026-07-10-21h`. Reutiliza el mismo valor en varios scopes cuando despliegas una versión del catálogo a varias tiendas o canales. Cada scope de tienda, canal y marca acepta un release solo una vez.
`x-force`	No	Si es `true` o `1`, los cambios de menús en el dashboard y vía API se sobrescribirán; de lo contrario, los cambios existentes persisten.
`x-publish`	No	Por defecto es `true`. Si es `false` o `0`, la sincronización se pausa antes de publicar para que puedas revisar y publicar desde el dashboard. Con `x-force: true`, la pausa ocurre también antes de podar overrides.

Parámetros de consulta

Parámetro	Requerido	Descripción
`fulfillment_id`	No	Identificador externo de fulfillment. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. Si se omite, el upsert aplica a todos los tipos de fulfillment. Ver Listar fulfillment.
`store_id`	No	Identificador externo de tienda. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. Si se omite, el upsert aplica a todas las tiendas.
`channel_id`	No	Identificador externo de canal. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. Si se omite, el upsert aplica a todos los canales.
`brand_id`	No	Identificador externo de marca. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. Omite o envía `__ANY__` para el default del comercio. Si se envía, acota el upsert a menús de esta marca.

Omite los parámetros de scope para un default opcional a nivel comercio — útil cuando aún no se eligió tienda, canal o fulfillment. Añade fulfillment_id, store_id, channel_id y/o brand_id para sobreescribir ese default en un contexto concreto. Omite un parámetro de scope o envía __ANY__ para persistir el wildcard en esa dimensión. Consulta Sincronización de menús para el flujo baseline y overrides recomendado.

Estilos de sync

El cuerpo de la solicitud es una unión discriminada por style. Fire spark valida cada variante con un esquema distinto.

Style	Cuándo usarlo
`DEFAULT`	Formato nativo de Fire spark — canales propios como app, web o kiosco.
`UBER_EATS`	Formato de la Uber Eats Menu API v2 — envía menús a Uber Eats sin mapear campos manualmente.

Envía "style": "DEFAULT" o "style": "UBER_EATS" en el nivel superior. En ambos estilos se envían las entidades del catálogo y hasta 10 definiciones de menú en la misma solicitud.

Request

Alterna entre DEFAULT y UBER_EATS en el panel de ejemplos de solicitud para ver ambas formas de payload. Ambas llamadas usan PUT con parámetros de scope (fulfillment_id, store_id, channel_id, brand_id).

curl --request PUT \
  --url 'https://firespark.cloud/api/integrations/v1/menus?fulfillment_id=delivery&store_id=centro&channel_id=app&brand_id=0001' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-release-id: 2026-07-03-baseline" \
  -d '{
    "style": "DEFAULT",
    "products": [
      {
        "id": "hamburguesa-clasica",
        "name": { "en_us": "Hamburguesa clásica" },
        "description": { "en_us": "Carne Angus con lechuga y tomate." },
        "image_url": "https://cdn.example.com/hamburguesa-clasica.jpg",
        "bundled_items": [],
        "pricing": {
          "minimum_quantity": 1,
          "maximum_quantity": 10,
          "is_tax_inclusive": true,
          "tax_rate": 0.15,
          "price": 12.99,
          "anchor_price": 14.99,
          "anchor_price_percentage": 0.13,
          "modifiers": [],
          "modifier_group_ids": ["elige-bebida"]
        },
        "availability": {
          "status": "AVAILABLE",
          "schedules": null,
          "out_of_stock_until": null
        },
        "metadata": {}
      },
      {
        "id": "refresco",
        "name": { "en_us": "Refresco" },
        "description": null,
        "image_url": null,
        "bundled_items": [],
        "pricing": {
          "minimum_quantity": 0,
          "maximum_quantity": 1,
          "is_tax_inclusive": true,
          "tax_rate": 0.15,
          "price": 0,
          "anchor_price": 0,
          "anchor_price_percentage": 0,
          "modifiers": [],
          "modifier_group_ids": []
        },
        "availability": {
          "status": "AVAILABLE",
          "schedules": null,
          "out_of_stock_until": null
        },
        "metadata": {}
      },
      {
        "id": "cola",
        "name": { "en_us": "Cola" },
        "description": null,
        "image_url": null,
        "bundled_items": [],
        "pricing": {
          "minimum_quantity": 0,
          "maximum_quantity": 1,
          "is_tax_inclusive": true,
          "tax_rate": 0.15,
          "price": 0,
          "anchor_price": 0,
          "anchor_price_percentage": 0,
          "modifiers": [],
          "modifier_group_ids": []
        },
        "availability": {
          "status": "AVAILABLE",
          "schedules": null,
          "out_of_stock_until": null
        },
        "metadata": {}
      }
    ],
    "categories": [
      {
        "id": "principales",
        "name": { "en_us": "Platos fuertes" },
        "description": { "en_us": "Hamburguesas y sándwiches" },
        "image_url": "https://cdn.example.com/mains.jpg",
        "items": [{ "type": "PRODUCT", "id": "hamburguesa-clasica" }],
        "availability": {
          "status": "ACTIVE",
          "schedules": null,
          "inactive_until": null
        },
        "metadata": {}
      }
    ],
    "modifier_groups": [
      {
        "id": "elige-bebida",
        "title": { "en_us": "Elige una bebida" },
        "description": null,
        "display_type": "LIST",
        "modifier_ids": ["cola", "refresco"],
        "minimum_quantity": 0,
        "maximum_quantity": 1,
        "charge_above_quantity": null,
        "metadata": {}
      }
    ],
    "menus": [
      {
        "id": "almuerzo-delivery",
        "name": { "en_us": "Menú almuerzo delivery" },
        "description": { "en_us": "Ítems de almuerzo entre semana para delivery" },
        "schedules": null,
        "metadata": {},
        "category_ids": ["principales"],
        "status": "ACTIVE"
      }
    ]
  }'

curl --request PUT \
  --url 'https://firespark.cloud/api/integrations/v1/menus?fulfillment_id=delivery&store_id=centro&channel_id=uber-eats&brand_id=0001' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-release-id: 2026-07-03-baseline" \
  -d '{
    "style": "UBER_EATS",
        "display_options": {
          "disable_item_instructions": true
        },
        "items": [
          {
            "id": "Coffee",
            "title": { "translations": { "en_us": "Coffee" } },
            "description": { "translations": { "en_us": "Deliciously roasted beans" } },
            "modifier_group_ids": { "ids": ["Add-milk"] },
            "price_info": { "price": 300 },
            "tax_info": { "tax_rate": 8 },
            "quantity_info": {}
          },
          {
            "id": "Milk",
            "title": { "translations": { "en_us": "Milk" } },
            "quantity_info": {
              "overrides": [
                {
                  "context_type": "MODIFIER_GROUP",
                  "context_value": "Add-milk",
                  "quantity": { "max_permitted": 1 }
                }
              ]
            },
            "price_info": {
              "price": 0,
              "overrides": [
                {
                  "context_type": "MODIFIER_GROUP",
                  "context_value": "Add-milk",
                  "price": 0
                }
              ]
            },
            "tax_info": { "tax_rate": 8 }
          }
        ],
        "categories": [
          {
            "id": "Drinks",
            "title": { "translations": { "en_us": "Drinks" } },
            "entities": [{ "type": "ITEM", "id": "Coffee" }]
          }
        ],
        "modifier_groups": [
          {
            "id": "Add-milk",
            "title": { "translations": { "en_us": "Add milk" } },
            "modifier_options": [{ "type": "ITEM", "id": "Milk" }],
            "quantity_info": { "quantity": { "max_permitted": 1 } },
            "display_type": null
          }
        ],
        "menus": [
          {
            "id": "All-day",
            "title": { "translations": { "en_us": "All day" } },
            "category_ids": ["Drinks"],
            "service_availability": [
              {
                "day_of_week": "monday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "tuesday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "wednesday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "thursday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "friday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "saturday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              },
              {
                "day_of_week": "sunday",
                "time_periods": [{ "start_time": "00:00", "end_time": "23:59" }]
              }
            ]
          }
        ]
      }'

Default
Uber Eats

Payload nativo de Fire spark. Productos, categorías y grupos de modificadores usan nombres de campo de Fire spark (name, pricing, items, etc.).

Payload de Uber Eats Menu API v2. Los productos de nivel superior son items; los textos localizados usan un objeto translations. Los precios son enteros en centavos en price_info.price.Consulta los example menu payloads de Uber para modificadores anidados, bundled items, tax labels y otros campos avanzados.

Cuerpo de la solicitud

Default
Uber Eats

Campo	Requerido	Descripción
`style`	Sí	Debe ser `"DEFAULT"`.
`products`	Sí	Definiciones de producto compartidas entre menús en esta solicitud. Al menos 1 entrada. Como máximo 1000.
`categories`	Sí	Definiciones de categoría compartidas entre menús en esta solicitud. Al menos 1 entrada. Como máximo 100.
`modifier_groups`	No	Definiciones de grupos de modificadores. Omite o envía `null` si no hay grupos. Como máximo 1000 si se envía.
`variant_groups`	No	Definiciones de grupos de variantes (preguntas que resuelven el id del producto). Como máximo 1000. Por defecto `[]`. Mira Variantes.
`recommendations`	No	Catálogo de recomendaciones compartido entre menús en esta solicitud. Como máximo 1000 si se envía. Por defecto `[]`.
`menus`	Sí	Definiciones de menú a crear o actualizar. Al menos 1 entrada. Como máximo 10.

Campos del menú

Cada objeto en menus acepta estos campos editables:

Campo	Requerido al crear	Descripción
`id`	Sí	Identificador externo del menú. Clave del upsert. Inmutable tras la creación.
`name`	Sí	Nombre visible localizado por locale (por ejemplo `en_us`). Cada valor tiene 1–1024 caracteres.
`description`	No	Descripción localizada por locale. `null` si se omite. Cada valor tiene 1–1024 caracteres.
`schedules`	No	Entradas de horario semanal. `null` u omitido para 24/7. Si se envía, deben incluir los 7 días sin periodos solapados. Ver Reglas de validación.
`metadata`	No	Metadatos del partner. Por defecto `{}`.
`category_ids`	Sí	IDs de categorías incluidas en este menú. Al menos 1 entrada. Como máximo 100.
`status`	Sí	`ACTIVE` o `INACTIVE`.

products

Cada producto en el cuerpo de la solicitud:

Campo	Requerido	Tipo	Descripción

| id | Sí | string | Identificador externo del producto. | | name | Sí | object | Nombre visible localizado por locale (por ejemplo en_us). | | description | No | object | null | Descripción localizada. null si se omite. | | image_url | No | string | URL de imagen del producto. JPG, PNG o WebP. Fire spark la copia a almacenamiento público y la sirve como URL de render para que agregues width, height y resize. null si se omite. | | bundled_items | No | array | Ítems incluidos en un bundle o combo. Por defecto []. | | pricing | Sí | object | Precio, impuestos, límites de cantidad y configuración de modificadores. Ver pricing. | | availability | Sí | object | Disponibilidad del producto. Ver campos abajo. | | labels | No | string[] | Etiquetas cortas para filtros y selección rápida en el Dashboard. Como máximo 64 cadenas (1–128 caracteres cada una). Por defecto []. | | tags | No | object | Tags clave/valor para reglas personalizadas avanzadas. Los valores pueden ser boolean, string o number. Por defecto {}. Ver Reglas personalizadas. | | metadata | No | object | Metadatos del partner. Por defecto {}. |Cada objeto availability:

Campo	Requerido	Tipo	Descripción
`status`	Sí	string	`AVAILABLE`, `HIDDEN` u `OUT_OF_STOCK`.
`schedules`	No	array \| null	Entradas de horario semanal. `null` u omitido sin restricción. Si se envía, deben incluir los 7 días. Ver Reglas de validación.
`out_of_stock_until`	No	string	Fecha y hora ISO 8601 opcional cuando el producto vuelve a stock.

Cada entrada de bundled_items:

Campo	Requerido	Tipo	Descripción

Ejemplo de producto

{
  "id": "hamburguesa-clasica",
  "name": { "en_us": "Hamburguesa clásica" },
  "description": { "en_us": "Carne Angus con lechuga y tomate." },
  "image_url": "https://cdn.example.com/hamburguesa-clasica.jpg",
  "bundled_items": [],
  "pricing": {
    "minimum_quantity": 1,
    "maximum_quantity": 10,
    "is_tax_inclusive": true,
    "tax_rate": 0.15,
    "price": 12.99,
    "anchor_price": 14.99,
    "anchor_price_percentage": 0.13,
    "modifiers": [],
    "modifier_group_ids": ["elige-bebida"]
  },
  "availability": {
    "status": "AVAILABLE",
    "schedules": null,
    "out_of_stock_until": null
  },
  "metadata": {}
}

categories

Cada categoría en el cuerpo de la solicitud:

Campo	Requerido	Tipo	Descripción

| id | Sí | string | Identificador externo de la categoría. | | name | Sí | object | Nombre visible localizado por locale. | | description | No | object | null | Descripción localizada. null si se omite. | | image_url | No | string | URL de imagen de la categoría. Debe ser JPG, PNG o WebP. null si se omite. | | items | Sí | array | Entradas ordenadas de la categoría. Al menos 1 entrada. Como máximo 1000. | | availability | Sí | object | Disponibilidad de la categoría. Ver campos abajo. | | labels | No | string[] | Etiquetas cortas para filtros y selección rápida en el Dashboard. Como máximo 64 cadenas (1–128 caracteres cada una). Por defecto []. | | tags | No | object | Tags clave/valor para reglas personalizadas avanzadas. Los valores pueden ser boolean, string o number. Por defecto {}. Ver Reglas personalizadas. | | metadata | No | object | Metadatos del partner. Por defecto {}. |Cada entrada en items:

Campo	Requerido	Tipo	Descripción
`type`	Sí	string	`CATEGORY` o `PRODUCT`.
`id`	Sí	string	Identificador externo de categoría o producto.

Cada objeto availability:

Campo	Requerido	Tipo	Descripción
`status`	Sí	string	`ACTIVE`, `INACTIVE` o `HIDDEN`.
`schedules`	No	array \| null	Entradas de horario semanal. `null` u omitido sin restricción. Si se envía, deben incluir los 7 días. Ver Reglas de validación.
`inactive_until`	No	string	Fecha y hora ISO 8601 opcional cuando la categoría vuelve a estar activa.

Ejemplo de categoría

{
  "id": "principales",
  "name": { "en_us": "Platos fuertes" },
  "description": { "en_us": "Hamburguesas y sándwiches" },
  "image_url": "https://cdn.example.com/mains.jpg",
  "items": [{ "type": "PRODUCT", "id": "hamburguesa-clasica" }],
  "availability": {
    "status": "ACTIVE",
    "schedules": null,
    "inactive_until": null
  },
  "metadata": {}
}

modifier_groups

Cada grupo de modificadores en el cuerpo de la solicitud:

Campo	Requerido	Tipo	Descripción

| id | Sí | string | Identificador externo del grupo de modificadores. Referenciado desde pricing.modifier_group_ids. | | title | Sí | object | Título localizado del grupo por locale. | | description | No | object | null | Descripción localizada. null si se omite. | | display_type | No | string | GRID o LIST. | | modifier_ids | Sí | array | UUIDs de productos modificadores en este grupo. 1–100 entradas. Un grupo de una sola opción es válido. | | minimum_quantity | Sí | number | Selecciones mínimas requeridas. ≥ 0. | | maximum_quantity | Sí | number | Selecciones máximas permitidas. 0–1,000,000. | | charge_above_quantity | No | number | Selecciones gratuitas antes de cobrar adicionales. Opcional. | | metadata | No | object | Metadatos del partner. Por defecto {}. |

Ejemplo de grupo de modificadores

{
  "id": "elige-bebida",
  "title": { "en_us": "Elige una bebida" },
  "description": null,
  "display_type": "LIST",
  "modifier_ids": ["cola", "refresco"],
  "minimum_quantity": 0,
  "maximum_quantity": 1,
  "charge_above_quantity": null,
  "metadata": {}
}

recommendations

Cada recomendación en el catálogo de nivel superior:

Campo	Requerido	Tipo	Descripción
`id`	Sí	string	Identificador externo de la recomendación. Debe ser único en la solicitud.
`title`	Sí	object	Nombre visible localizado por locale.
`description`	No	object \| null	Descripción localizada. `null` si se omite.
`type`	Sí	string	`UPSELL`, `CROSS_SELL` o `DOWNSELL`.
`target_product_id`	Sí	string	`id` del producto a recomendar. Debe existir en `products`.
`metadata`	No	object	Metadatos del partner. Por defecto `{}`.

Ejemplo de recomendación

{
  "id": "upsell-fries",
  "type": "UPSELL",
  "title": { "en_us": "Add fries" },
  "description": { "en_us": "Side of seasoned fries." },
  "target_product_id": "fries",
  "metadata": {}
}

variant_groups

Cada grupo de variantes:

Campo	Requerido	Tipo	Descripción
`id`	Sí	string	Identificador externo del grupo de variantes. Referenciado desde `pricing.variant_group_ids`.
`title`	Sí	object	Pregunta localizada por locale.
`description`	No	object \| null	Descripción localizada.
`display_type`	No	string	`GRID` o `LIST`.
`variants`	Sí	array	Opciones del grupo. Entre 1 y 100. Mira los campos abajo.
`metadata`	No	object	Metadatos del partner. Por defecto `{}`.

Cada entrada en variants:

Campo	Requerido	Tipo	Descripción
`id`	Sí	string	Identificador de la opción, único entre todos los grupos de variantes. Referenciado desde `pricing.variants[].variant_group_option_ids`.
`name`	Sí	object	Etiqueta localizada de la opción.
`description`	No	object \| null	Descripción localizada.
`image_url`	No	string \| null	URL de imagen de la opción. Debe ser JPG, PNG o WebP; se copia al almacenamiento de Firespark igual que las imágenes de productos.
`product_ids`	Sí	array	Productos variante a los que puede llevar esta opción. Cada uno debe existir y listar esta opción en su `pricing.variants`. Entre 1 y 1000.
`metadata`	No	object	Metadatos del partner. Por defecto `{}`.

Example variant group

{
  "id": "size",
  "title": { "en_us": "Size" },
  "description": null,
  "display_type": "GRID",
  "variants": [
    { "id": "medium", "name": { "en_us": "Medium" }, "description": null, "image_url": null, "product_ids": ["pep-m-thin", "pep-m-thick"], "metadata": {} },
    { "id": "large", "name": { "en_us": "Large" }, "description": null, "image_url": null, "product_ids": ["pep-l-thin", "pep-l-thick"], "metadata": {} }
  ],
  "metadata": {}
}

pricing

Precio de producto en el cuerpo de la solicitud:

Campo	Requerido	Tipo	Descripción

| minimum_quantity | No | number | Unidades mínimas por pedido. ≥ 0. Por defecto 0. | | maximum_quantity | No | number | Unidades máximas por pedido. 0–1,000,000. Por defecto 1000000. | | is_tax_inclusive | Sí | boolean | Si price incluye impuestos. | | tax_rate | Sí | number | Tasa de impuesto como decimal (por ejemplo 0.15 para 15%). 0–1. | | price | Sí | number | Precio de lista. ≥ 0. | | anchor_price | No | number | Precio de referencia para tachado o comparación. ≥ 0. | | anchor_price_percentage | No | number | Descuento mostrado respecto a anchor_price. 0–1. | | starting_price | No | number | null | Precio “Desde” de referencia. Si lo omites, Fire spark calcula durante el sync el precio más bajo que cumple todos los modificadores obligatorios. Envía null para no mostrarlo nunca. ≥ 0. | | modifiers | No | array | Overrides de precio y selección por grupo. Por defecto []. | | modifier_group_ids | No | array | Identificadores externos de grupos de modificadores del producto. Por defecto []. | | variant_group_ids | No | array | Grupos de variantes que se preguntan en este producto base. Cada id debe existir en variant_groups y aparecer una vez. Un producto con grupos de variantes no puede tener modifier_group_ids. Por defecto []. Mira Variantes. | | variants | No | array | Cuando este producto es una variante: una entrada por base, cada una { "product_id": id de la base, "variant_group_option_ids": [...] } con exactamente una opción de cada grupo de la base. Por defecto []. | | recommendations_ids | No | array | IDs de recomendaciones a mostrar en este producto. Cada id debe existir en recommendations de nivel superior. Por defecto []. | | recommendations | No | array | Configuración de visualización por recomendación en este producto. Por defecto []. |Cada objeto en recommendations (dentro de pricing) vincula una recomendación del catálogo al producto padre:

Campo	Requerido	Tipo	Descripción
`recommendation_id`	Sí	string	Debe coincidir con un `id` de `recommendations` de nivel superior.
`default_quantity`	No	number	Cantidad preseleccionada del producto recomendado en esta línea padre. Por defecto `0`. Independiente de `default_quantity` en `pricing.modifiers`.

Cada objeto en modifiers configura un grupo de modificadores referenciado en modifier_group_ids. Acepta los mismos campos de precio que el producto padre, más campos específicos del modificador:

Campo	Requerido	Tipo	Descripción

Ejemplo de entrada en modifiers

{
  "modifier_group_id": "choose-drink",
  "minimum_quantity": 0,
  "maximum_quantity": 1,
  "is_tax_inclusive": true,
  "tax_rate": 0.15,
  "price": 0,
  "anchor_price": 0,
  "anchor_price_percentage": 0,
  "default_quantity": 1,
  "charge_above_quantity": 0,
  "display_type": "RADIO",
  "image_url": "https://cdn.example.com/cola-in-combo.jpg"
}

Campo	Requerido	Descripción
`style`	Sí	Debe ser `"UBER_EATS"`.
`items`	Sí	Ítems y opciones modificadoras. Productos y modificadores comparten este arreglo. Al menos 1 entrada. Como máximo 1000.
`categories`	Sí	Definiciones de categoría con `entities` que referencian IDs de ítems. Al menos 1 entrada. Como máximo 100.
`modifier_groups`	No	Definiciones de grupos de modificadores. Omite o envía `null` si no hay grupos. Como máximo 1000 si se envía.
`recommendations`	No	Catálogo de recomendaciones. Misma forma que `DEFAULT` tras el mapeo. Como máximo 1000 si se envía. Por defecto `[]`.
`menus`	Sí	Definiciones de menú a crear o actualizar. Al menos 1 entrada. Como máximo 10.
`menu_type`	No	`MENU_TYPE_FULFILLMENT_DELIVERY`, `MENU_TYPE_FULFILLMENT_PICK_UP` o `MENU_TYPE_FULFILLMENT_DINE_IN`. Por defecto delivery.
`display_options`	No	Configuración de visualización de la tienda, como `disable_item_instructions`.

Campos del menú

Cada objeto en menus usa la forma de menú de Uber Eats:

Campo	Requerido al crear	Descripción
`id`	Sí	Identificador externo del menú. Clave del upsert. Inmutable tras la creación.
`title`	Sí	`MultiLanguageText` con mapa `translations` (por ejemplo `en_us`).
`subtitle`	No	Subtítulo opcional como `MultiLanguageText`.
`service_availability`	Sí	Disponibilidad semanal con `day_of_week` y `time_periods` (`HH:MM`).
`category_ids`	Sí	IDs de categorías activas mientras este menú está disponible.

MultiLanguageText

Los textos localizados envuelven los valores en translations:

{
  "translations": {
    "en_us": "Coffee"
  }
}

items

Cada ítem en el cuerpo de la solicitud. Productos de nivel superior y opciones modificadoras son ítems.

Campo	Requerido	Tipo	Descripción

| id | Sí | string | Identificador único del ítem en tu POS o RMS. | | title | Sí | object | MultiLanguageText requerido. | | description | No | object | MultiLanguageText opcional. | | image_url | No | string | URL pública de imagen. Opcional. | | external_data | No | string | Metadatos del partner (máx. 1024 caracteres). Opcional. | | price_info | Sí | object | Precio en centavos más overrides por contexto. Ver price_info. | | quantity_info | No | object | Restricciones de cantidad y overrides por modificador. Opcional. | | modifier_group_ids | No | object | { "ids": [...] } con overrides por contexto opcionales. Opcional. | | tax_info | No | object | tax_rate, vat_rate_percentage o mx_ieps_rate. Opcional. | | suspension_info | No | object | Reglas de suspensión por falta de stock. Opcional. | | bundled_items | No | array | Ítems siempre incluidos en un combo. Opcional. | | dish_info | No | object | Etiquetas dietéticas y clasificaciones. Opcional. | | visibility_info | No | object | Ventanas horarias de visibilidad del ítem. Opcional. | | tax_label_info | No | object | Etiquetas de clasificación fiscal. Opcional. | | product_info | No | object | GTIN, PLU o identificadores internos del comercio. Opcional. | | selling_info | No | object | Configuración de venta por peso o por unidad. Opcional. |

Ejemplo de ítem

{
  "id": "Coffee",
  "title": { "translations": { "en_us": "Coffee" } },
  "description": { "translations": { "en_us": "Deliciously roasted beans" } },
  "modifier_group_ids": { "ids": ["Add-milk"] },
  "price_info": { "price": 300 },
  "tax_info": { "tax_rate": 8 },
  "quantity_info": {}
}

Response

El endpoint responde de forma asíncrona. Fire spark inicia una sincronización de menú en segundo plano y responde de inmediato.

Estado	Cuándo	Cuerpo
`201`	Sync aceptado y encolado	`{ "message": "Sync accepted: …" }` — conteos de productos, menús, categorías y grupos de modificadores recibidos
`202`	Ya hay un sync en curso para la misma tienda, canal y marca	`{ "message": "Sync already in progress for this store/channel.", "runId": "…" }` — `runId` identifica el workflow activo
`409`	Ya hay un sync en curso o completado para el mismo release y scope	`{ "message": "Sync already exists for this release and scope.", "menuSyncId": "…" }` — reintenta con el mismo `x-release-id` solo si el sync previo está en `FAILED` o `CANCELLED`

Trata 202 como éxito: el catálogo ya se está procesando. Reintenta solo cuando el sync actual termine o falle. Trata 409 como éxito al reenviar un release que ya completó. Si el sync previo para ese release y scope está en FAILED o CANCELLED, reenvía el mismo x-release-id.

Límites de tasa

GET y PUT /api/integrations/v1/menus comparten un límite de 30 solicitudes por 10 segundos por comercio. La clave es el merchant_id de tu access token. Envía una solicitud a la vez por comercio — espera la respuesta antes de iniciar la siguiente. No paralelices upserts ni lecturas de menú para el mismo comercio. Cada respuesta incluye headers de rate limit para saber cuándo puedes emitir la siguiente solicitud:

Header	Descripción
`X-RateLimit-Limit`	Máximo de solicitudes por ventana (`30`)
`X-RateLimit-Reset`	Segundos hasta que se reinicia la ventana actual (`10`)
`X-RateLimit-Remaining`	Solicitudes restantes en la ventana — presente en `429` (`0`)
`Retry-After`	Segundos de espera antes de reintentar — solo en respuestas `429`

Si superas el límite, la API responde 429 Too Many Requests. Espera Retry-After segundos (o X-RateLimit-Reset) antes de enviar otra solicitud para ese comercio.

Respuestas de error

| Estado | Descripción | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | | 400 | Error de validación — valores inválidos, campos requeridos ausentes o forma semanal inválida. El cuerpo es { "error": "Invalid fields", "details": { "<path>": "<message>" } }. Ver Reglas de validación. | | 401 | Access token ausente o inválido. | | 403 | El token no incluye el scope menus:write. | | 409 | La tienda, canal o fulfillment referenciados no existen para este comercio, o ya existe un sync para el mismo release y scope. | | 429 | Límite de tasa excedido — espera Retry-After / X-RateLimit-Reset antes de reintentar. Ver Límites de tasa. | |

Documentación de API

Endpoints

Guías

Recursos

Headers

Parámetros de consulta

Estilos de sync

Request

Cuerpo de la solicitud

Campos del menú

Campos del menú

MultiLanguageText

Response

Límites de tasa

Respuestas de error

​Headers

​Parámetros de consulta

​Estilos de sync

​Request

​Cuerpo de la solicitud

​Campos del menú

​Campos del menú

​MultiLanguageText

​Response

​Límites de tasa

​Respuestas de error

Headers

Parámetros de consulta

Estilos de sync

Request

Cuerpo de la solicitud

Campos del menú

Campos del menú

MultiLanguageText

Response

Límites de tasa

Respuestas de error