Variantes

Algunos POS guardan un PLU distinto por cada configuración de un ítem. En este ejemplo cada combinación de tamaño y masa es su propio producto, pero el cliente ve una sola tarjeta por pizza y responde dos preguntas. Las respuestas deciden qué id de producto entra al pedido. Mira Productos — variantes para los conceptos.

Qué incluye este ejemplo

Producto base	Grupos de variantes	Productos variante	Notas
`pepperoni`	`size`, `crust`	`pep-m-thin`, `pep-m-thick`, `pep-l-thin`, `pep-l-thick`	Existen todas las combinaciones
`hawaiian`	`size`, `crust`	`haw-m-thin`, `haw-m-thick`, `haw-l-thick`	No hay grande de masa delgada; `haw-m-thick` está agotado

Ambas bases comparten los grupos size y crust. Cada opción lista en product_ids los productos de las dos pizzas.
Las pizzas grandes tienen el grupo de modificadores extra-toppings; las medianas no tienen ninguno. Los grupos de modificadores van en los productos variante, nunca en la base.
Las opciones de tamaño tienen imagen y descripción; las de masa no.

Qué ve el cliente

Tomando como ejemplo la pizza hawaiana:

La tarjeta muestra Desde $12.99. Como se omitió el precio desde, la sincronización lo calculó a partir de la variante seleccionable más barata (haw-m-thin).
El detalle pregunta primero Tamaño y luego Masa, y muestra los grupos de modificadores solo cuando la variante ya está resuelta.
Al elegir Grande, Delgada desaparece porque no existe la hawaiana grande delgada. Como Gruesa queda como única opción, se selecciona automáticamente.
Al elegir Mediana, Gruesa sigue visible pero deshabilitada porque haw-m-thick está agotado.
La línea del carrito es haw-l-thick a $17.99, más los toppings extra. La base hawaiian nunca aparece en un pedido.

Request

curl --request PUT \
  --url 'https://firespark.cloud/api/integrations/v1/menus?fulfillment_id=delivery&store_id=downtown&channel_id=app&brand_id=0001' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @variants.json

variants.json

{
  "style": "DEFAULT",
  "products": [
    {
      "id": "pepperoni",
      "name": {
        "en_us": "Pepperoni pizza",
        "es_ec": "Pizza de pepperoni"
      },
      "description": {
        "en_us": "Pick a size and crust.",
        "es_ec": "Elige tamaño y masa."
      },
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 0,
        "anchor_price": 0,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": [],
        "variant_group_ids": [
          "size",
          "crust"
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "hawaiian",
      "name": {
        "en_us": "Hawaiian pizza",
        "es_ec": "Pizza hawaiana"
      },
      "description": {
        "en_us": "Pick a size and crust.",
        "es_ec": "Elige tamaño y masa."
      },
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 0,
        "anchor_price": 0,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": [],
        "variant_group_ids": [
          "size",
          "crust"
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "pep-m-thin",
      "name": {
        "en_us": "Pepperoni pizza Medium Thin",
        "es_ec": "Pizza de pepperoni Mediana Delgada"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 11.99,
        "anchor_price": 11.99,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": [],
        "variants": [
          {
            "product_id": "pepperoni",
            "variant_group_option_ids": [
              "medium",
              "thin"
            ]
          }
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "pep-m-thick",
      "name": {
        "en_us": "Pepperoni pizza Medium Thick",
        "es_ec": "Pizza de pepperoni Mediana Gruesa"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 12.99,
        "anchor_price": 12.99,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": [],
        "variants": [
          {
            "product_id": "pepperoni",
            "variant_group_option_ids": [
              "medium",
              "thick"
            ]
          }
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "pep-l-thin",
      "name": {
        "en_us": "Pepperoni pizza Large Thin",
        "es_ec": "Pizza de pepperoni Grande Delgada"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 15.99,
        "anchor_price": 15.99,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [
          "extra-toppings"
        ],
        "modifiers": [],
        "variants": [
          {
            "product_id": "pepperoni",
            "variant_group_option_ids": [
              "large",
              "thin"
            ]
          }
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "pep-l-thick",
      "name": {
        "en_us": "Pepperoni pizza Large Thick",
        "es_ec": "Pizza de pepperoni Grande Gruesa"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 16.99,
        "anchor_price": 16.99,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [
          "extra-toppings"
        ],
        "modifiers": [],
        "variants": [
          {
            "product_id": "pepperoni",
            "variant_group_option_ids": [
              "large",
              "thick"
            ]
          }
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "haw-m-thin",
      "name": {
        "en_us": "Hawaiian pizza Medium Thin",
        "es_ec": "Pizza hawaiana Mediana Delgada"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 12.99,
        "anchor_price": 12.99,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": [],
        "variants": [
          {
            "product_id": "hawaiian",
            "variant_group_option_ids": [
              "medium",
              "thin"
            ]
          }
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "haw-m-thick",
      "name": {
        "en_us": "Hawaiian pizza Medium Thick",
        "es_ec": "Pizza hawaiana Mediana Gruesa"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 13.99,
        "anchor_price": 13.99,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": [],
        "variants": [
          {
            "product_id": "hawaiian",
            "variant_group_option_ids": [
              "medium",
              "thick"
            ]
          }
        ]
      },
      "availability": {
        "status": "OUT_OF_STOCK",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "haw-l-thick",
      "name": {
        "en_us": "Hawaiian pizza Large Thick",
        "es_ec": "Pizza hawaiana Grande Gruesa"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 1,
        "maximum_quantity": 10,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 17.99,
        "anchor_price": 17.99,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [
          "extra-toppings"
        ],
        "modifiers": [],
        "variants": [
          {
            "product_id": "hawaiian",
            "variant_group_option_ids": [
              "large",
              "thick"
            ]
          }
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "extra-cheese",
      "name": {
        "en_us": "Extra cheese",
        "es_ec": "Queso extra"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 0,
        "maximum_quantity": 3,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 1.5,
        "anchor_price": 1.5,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": [
          {
            "modifier_group_id": "extra-toppings",
            "minimum_quantity": 0,
            "maximum_quantity": 2,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 1.5,
            "anchor_price": 1.5,
            "anchor_price_percentage": 0,
            "default_quantity": 0,
            "charge_above_quantity": 0,
            "display_type": "QUANTITY"
          }
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    },
    {
      "id": "jalapenos",
      "name": {
        "en_us": "Jalapeños",
        "es_ec": "Jalapeños"
      },
      "description": null,
      "image_url": null,
      "status": "ACTIVE",
      "bundled_items": [],
      "pricing": {
        "minimum_quantity": 0,
        "maximum_quantity": 3,
        "is_tax_inclusive": true,
        "tax_rate": 0.15,
        "price": 1.0,
        "anchor_price": 1.0,
        "anchor_price_percentage": 0,
        "modifier_group_ids": [],
        "modifiers": [
          {
            "modifier_group_id": "extra-toppings",
            "minimum_quantity": 0,
            "maximum_quantity": 2,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 1.0,
            "anchor_price": 1.0,
            "anchor_price_percentage": 0,
            "default_quantity": 0,
            "charge_above_quantity": 0,
            "display_type": "QUANTITY"
          }
        ]
      },
      "availability": {
        "status": "AVAILABLE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    }
  ],
  "categories": [
    {
      "id": "pizzas",
      "name": {
        "en_us": "Pizzas",
        "es_ec": "Pizzas"
      },
      "description": null,
      "status": "ACTIVE",
      "items": [
        {
          "type": "PRODUCT",
          "id": "pepperoni"
        },
        {
          "type": "PRODUCT",
          "id": "hawaiian"
        }
      ],
      "availability": {
        "status": "ACTIVE",
        "schedules": null,
        "out_of_stock_until": null
      },
      "metadata": {}
    }
  ],
  "modifier_groups": [
    {
      "id": "extra-toppings",
      "title": {
        "en_us": "Extra toppings",
        "es_ec": "Toppings extra"
      },
      "description": null,
      "display_type": "LIST",
      "modifier_ids": [
        "extra-cheese",
        "jalapenos"
      ],
      "minimum_quantity": 0,
      "maximum_quantity": 3,
      "charge_above_quantity": null,
      "metadata": {}
    }
  ],
  "variant_groups": [
    {
      "id": "size",
      "title": {
        "en_us": "Size",
        "es_ec": "Tamaño"
      },
      "description": null,
      "display_type": "GRID",
      "metadata": {},
      "variants": [
        {
          "id": "medium",
          "name": {
            "en_us": "Medium",
            "es_ec": "Mediana"
          },
          "description": {
            "en_us": "30 cm",
            "es_ec": "30 cm"
          },
          "image_url": "https://cdn.example.com/pizza/medium.png",
          "product_ids": [
            "pep-m-thin",
            "pep-m-thick",
            "haw-m-thin",
            "haw-m-thick"
          ],
          "metadata": {}
        },
        {
          "id": "large",
          "name": {
            "en_us": "Large",
            "es_ec": "Grande"
          },
          "description": {
            "en_us": "40 cm",
            "es_ec": "40 cm"
          },
          "image_url": "https://cdn.example.com/pizza/large.png",
          "product_ids": [
            "pep-l-thin",
            "pep-l-thick",
            "haw-l-thick"
          ],
          "metadata": {}
        }
      ]
    },
    {
      "id": "crust",
      "title": {
        "en_us": "Crust",
        "es_ec": "Masa"
      },
      "description": null,
      "display_type": "LIST",
      "metadata": {},
      "variants": [
        {
          "id": "thin",
          "name": {
            "en_us": "Thin",
            "es_ec": "Delgada"
          },
          "description": null,
          "image_url": null,
          "product_ids": [
            "pep-m-thin",
            "pep-l-thin",
            "haw-m-thin"
          ],
          "metadata": {}
        },
        {
          "id": "thick",
          "name": {
            "en_us": "Thick",
            "es_ec": "Gruesa"
          },
          "description": null,
          "image_url": null,
          "product_ids": [
            "pep-m-thick",
            "pep-l-thick",
            "haw-m-thick",
            "haw-l-thick"
          ],
          "metadata": {}
        }
      ]
    }
  ],
  "recommendations": [],
  "menus": [
    {
      "id": "all-day",
      "name": {
        "en_us": "All day",
        "es_ec": "Todo el día"
      },
      "description": null,
      "schedules": null,
      "metadata": {},
      "category_ids": [
        "pizzas"
      ],
      "status": "ACTIVE"
    }
  ]
}

Puntos clave

La base abre las preguntas. hawaiian define pricing.variant_group_ids: ["size", "crust"] y deja vacío modifier_group_ids.
El precio de la base nunca se cobra. Aquí las bases usan price: 0, así que la tarjeta muestra el precio Desde calculado (las tarjetas lo muestran cuando starting_price es mayor que price).
Cada producto variante dice cómo se selecciona. haw-l-thick define pricing.variants: [{ "product_id": "hawaiian", "variant_group_option_ids": ["large", "thick"] }], con una opción de cada grupo de la base.
Cada opción lista sus productos. La opción large lista todas las pizzas grandes de ambas bases. La sincronización rechaza el payload si una opción y el pricing.variants de un producto no coinciden.
Las combinaciones que no existen simplemente se omiten. No hay haw-l-thin, así que el cliente no puede llegar a esa combinación.
Solo las categorías listan la base. Los productos variante no están en ninguna categoría; entran al menú porque una base del menú apunta a ellos.
Un producto puede ser variante de varias bases. Agrega una entrada en pricing.variants por cada base, cada una con sus opciones.

Documentación de API

Endpoints

Guías

Recursos

Qué incluye este ejemplo

Qué ve el cliente

Request

Puntos clave

Relacionado

Productos — variantes

Grupos de modificadores multinivel

​Qué incluye este ejemplo

​Qué ve el cliente

​Request

​Puntos clave

​Relacionado

Productos — variantes

Grupos de modificadores multinivel

Qué incluye este ejemplo

Qué ve el cliente

Request

Puntos clave

Relacionado