Combora — Manual de usuario

1Qué es Combora

Combora crea packs (bundles) y ofertas automáticas en tu tienda Shopify: agrupa productos, aplica el descuento correcto en el carrito y el checkout, y muestra la oferta en tu tema con bloques listos para usar. Tú configuras la oferta en el admin; Combora se encarga de que el precio cobrado sea siempre exacto — el descuento lo calcula una Shopify Function en el propio checkout, no un script en el navegador.

Hay 8 tipos de pack. Esta tabla te ayuda a elegir:

Si dudas entre tipos, la propia app trae una guía: en Crear pack, el enlace "¿No sabes cuál elegir?" abre un asistente, y cada tipo tiene un panel "Ver cómo funciona" con ejemplos.

2Primeros pasos

2.1 Qué crea la app al instalarse

Al instalar Combora no cambia nada visible en tu tienda. La app prepara en segundo plano las estructuras de datos donde publicará tus packs (metaobjetos y metafields con el prefijo combora — el detalle técnico está en el anexo para desarrolladores) y un único descuento automático llamado "Combora" en Descuentos, que es el que aplica todos los precios. No lo borres ni lo edites a mano: la app lo mantiene sola.

2.2 Activar el motor de regalos (app embed)

Si vas a usar Regalo por compra (o combos con regalo), activa el app embed Combora Gift: Tienda online → Personalizar → Configuración del tema → App embeds → Combora Gift. Es el componente que añade y retira el regalo del carrito automáticamente. Sin él, el descuento del regalo seguiría siendo correcto, pero el producto-regalo no se añadiría solo.

2.3 Añadir los bloques al tema

Cada tipo de pack se muestra en la tienda con un bloque de tema. Se añaden una sola vez en Tienda online → Personalizar, en la plantilla correspondiente:

No hace falta memorizarlo: el editor de cada pack incluye una tarjeta "Dónde aparece" que nombra el bloque correcto y un enlace "Ver en tu tema publicado" que abre el editor de temas con ese bloque ya preparado para insertarse en la plantilla adecuada.

3Tour de la app

La app vive en Apps → Combora y tiene seis pestañas:

Packs

La lista de todos tus packs: búsqueda por nombre, filtro por estado (Publicado / Borrador), acciones por fila (duplicar, publicar/pasar a borrador, eliminar) y selección múltiple con acciones masivas. Desde aquí se crea todo con Crear pack.

Analítica

Métricas de rendimiento de tus packs sobre pedidos reales: ingresos atribuidos, % de pedidos con pack, ahorro entregado, valor medio de pedido y un gráfico temporal. Detalle en la sección 16.

Planes

Tu plan actual y las opciones de upgrade. El plan Gratis permite 3 packs publicados simultáneamente; los planes de pago no tienen límite (sección 17).

Ayuda

Preguntas frecuentes y explicaciones de conceptos (arbitraje entre packs, regalos, bloques).

Diagnóstico (pestaña dentro de Ayuda)

El panel de salud y soporte vive como pestaña dentro de Ayuda (selector "Guías | Diagnóstico" arriba): chequeos en vivo de toda la instalación, el registro de eventos y el informe de soporte que copias cuando algo va mal (sección 18).

Chat de soporte (burbuja flotante)

En la esquina inferior derecha de todas las pantallas hay una burbuja de chat 💬 para hablar directamente con soporte: conversaciones por tema, historial, y aviso de si soporte está disponible o ausente. Solo se comparte lo que escribes — nunca datos de tus clientes.

Ajustes

Idioma de la app (7 idiomas), sincronización manual de descuentos y el acceso para desarrolladores.

4Anatomía del editor

Todos los tipos comparten el mismo editor; cambia solo la sección de productos y precio. Al crear un pack nuevo se ve así:

4.1 Datos básicos

Nombre del pack

Interno. Solo tú lo ves; sirve para encontrarlo en tu lista.

Título en la tienda

Lo que ve el cliente como nombre de la oferta en el carrito y el checkout. Es traducible. También es el texto de la línea de descuento (recortado a 100 caracteres).

Texto de la etiqueta

Una insignia corta opcional ("Mejor valor") que tu tema puede mostrar como destacado.

4.2 Programación

Fechas de inicio y fin opcionales. Vacías = la oferta se activa al publicar y no caduca. Un pack publicado fuera de su ventana deja de aplicar el descuento automáticamente y vuelve a aplicarlo al entrar en ventana, sin tocar nada.

4.3 Productos

Según el tipo, eliges productos concretos, variantes, una colección o toda la tienda. El selector de Shopify es el estándar:

4.4 Precio

Cada tipo tiene su propia sección (porcentaje, importe, precio fijo, niveles, recompensa…). Se documenta en el capítulo de cada tipo. En todos los casos el precio que se cobra lo calcula Shopify en el checkout con la configuración publicada: lo que muestran los bloques es informativo.

4.5 Suscripciones

Por defecto un cliente no puede comprar un artículo del pack como suscripción (protege el checkout de precios de suscripción mezclados con descuentos de pack). En los tipos donde tiene sentido (mix & match, arma tu caja y regalo por compra) hay un opt-in avanzado "Permitir suscripciones en este pack".

4.6 El rail derecho

Estado + acción

Publicar (o Actualizar pack si ya está publicado) y Pasar a borrador. Publicar pone la oferta en vivo; pasar a borrador la retira conservando toda la configuración.

Modo prueba

Marca "Publicar en modo prueba" para probar el pack sin riesgo: los bloques solo se muestran en el editor de temas y en las vistas previas (nunca en tu tema publicado), y el descuento solo se aplica a clientes con la etiqueta combora-test. Para recorrer el checkout completo, añade esa etiqueta a tu propio cliente de pruebas (Admin → Clientes) e inicia sesión con él en la tienda. Cuando todo se vea bien, desmarca la casilla y pulsa Actualizar pack — pasa a en vivo. En la lista, un pack en prueba lleva la insignia Modo prueba.

Antes de publicar

La checklist que bloquea la publicación hasta completar lo imprescindible (título, productos, precio…).

Lo que ve tu cliente

Vista previa del contenido de la oferta y el ahorro. El aspecto final depende de tu tema.

Estilo de la vista previa

Acento y radio de esquina — son los mismos ajustes que luego configuras en el bloque del tema.

Dónde aparece

El bloque de tema que muestra este tipo y el enlace directo al editor de temas.

4.7 Avisos que puede mostrar el editor

• Solapamiento: si los productos del pack ya están en otros packs publicados, un banner avisa: "En el checkout solo se aplica la mejor oferta por línea: los packs no se acumulan". No es un error — es información (ver sección 13).
• Sin ahorro / precio 0: si la configuración no produce ningún descuento (o produce un precio 0), el editor lo señala antes de publicar.
• Pool vacío: una colección sin productos elegibles también se avisa.

4.8 Editar un pack publicado

Al editar un pack publicado, los cambios no salen a la tienda hasta que pulses "Actualizar pack". Así puedes preparar cambios con calma. "Pasar a borrador" retira la oferta de la tienda al momento; volver a publicar la restaura tal cual.

5Pack fijo

Un conjunto cerrado de productos que se vende como una unidad. Es el único tipo que además crea un producto comprable de 1 clic en tu catálogo: un producto "padre" (bundle nativo de Shopify) cuyos componentes se expanden automáticamente en el checkout.

5.1 Configuración

1. Productos: añade los componentes (variantes concretas) y la cantidad de cada uno. Máximo 30 componentes por pack.
2. Precio — dos modos excluyentes:
   • Precio fijo del pack: escribes el precio total (p. ej. $1,349.95). El ahorro se calcula contra la suma de los componentes.
   • Aplicar un descuento: porcentaje o importe sobre la suma de los componentes.
3. Publica. Al publicar, Combora crea (o actualiza) el producto padre en tu catálogo.

5.2 Qué ve tu cliente

5.3 Detalles y limitaciones del tipo

• Los componentes deben ser variantes con stock; el producto padre hereda la disponibilidad.
• El producto padre se gestiona solo: al pasar a borrador o eliminar el pack, se retira de la tienda (verificado durante este manual). No lo borres a mano.
• Máximo 30 componentes. El precio fijo se reparte entre componentes con redondeo exacto (la suma de las partes siempre iguala el total).
• El pack fijo también aplica si el cliente añade los componentes por separado en las cantidades exactas — el checkout agrupa y descuenta igual.

6Combina y ahorra (mix & match)

El cliente elige al menos N artículos de un grupo y todo el grupo sale con descuento.

6.1 Configuración

1. Productos: el grupo elegible puede ser variantes específicas, productos, una colección (se actualiza sola) o toda la tienda.
2. Cantidad: el mínimo de artículos para calificar, y opcionalmente un máximo (por encima del máximo, los artículos extra se pagan a precio normal).
3. Descuento: porcentaje o importe, aplicado a todos los artículos elegibles del carrito cuando se alcanza el mínimo.

6.2 Qué ve tu cliente

6.3 Detalles del tipo

• Un carrito por debajo del mínimo no se bloquea: el cliente paga precio completo hasta calificar.
• Con máximo definido, el selector bloquea marcar más casillas al llegar al tope, y en el carrito solo las primeras unidades hasta el máximo reciben descuento.
• Las cantidades cuentan por unidades: 3 unidades de un mismo producto elegible también califican un mínimo de 3.

7Descuento por volumen

Niveles de precio por cantidad: "compra al menos 2 → 10%, al menos 4 → 20%". La cantidad total de artículos elegibles en el carrito decide el nivel, y el descuento del nivel alcanzado se aplica a todos ellos.

7.1 Configuración

1. Productos: variantes, productos, colección o toda la tienda (igual que mix).
2. Niveles: cada nivel es "Compra al menos N" + descuento (porcentaje o importe). Añade tantos como quieras con "Agregar nivel".

7.2 Qué ve tu cliente

7.3 Detalles del tipo

• Solo aplica el nivel más alto alcanzado (no se suman niveles).
• Los niveles pueden mezclar tipos de valor (unos %, otros importe).
• El importe fijo de descuento se reparte entre las líneas de forma proporcional y exacta.

8Compra X, llévate Y (BOGO)

Al comprar X unidades, las siguientes Y unidades salen con recompensa. La recompensa puede ser gratis (100%), un porcentaje, un importe de descuento o un precio fijo por unidad.

8.1 Configuración

8.2 Qué ve tu cliente

8.3 Detalles del tipo

• La oferta se repite por bloques completos: con "2+1", 6 unidades = 2 gratis; 5 unidades = 1 gratis.
• El bloque de tema que la muestra es Combora volume table (presenta el "compra X, llévate Y" como una tabla de ahorro).
• La recompensa "precio fijo" cobra ese precio exacto por cada unidad recompensada.

9Regalo por compra (GWP)

Añade un producto de regalo (a $0.00) automáticamente cuando el carrito cumple la condición, y lo retira si deja de cumplirla. Es el tipo con más automatismo: el app embed Combora Gift gestiona el regalo sin que el cliente haga nada.

9.1 Configuración

1. El regalo: una variante concreta que se agrega cuando el cliente califica.
2. Condición para desbloquear — cuatro opciones:
   • Por gasto mínimo: el carrito alcanza un importe (p. ej. $50).
   • Por cantidad de productos: alcanza N unidades.
   • Gasto y cantidad (ambas): se exigen las dos.
   • Por llevar una combinación de productos: una lista concreta (de 2 a 5 artículos con sus cantidades) que debe estar completa en el carrito.
3. Qué cuenta para la condición: cualquier producto de la tienda, productos específicos o colecciones.

9.2 Qué ve tu cliente

9.3 Detalles y protecciones del tipo

• El propio regalo no cuenta para el gasto que califica.
• Si el cliente elimina el regalo a mano, la app lo respeta y no lo vuelve a añadir en esa sesión.
• Si el regalo se queda sin stock, la oferta simplemente no lo añade (no bloquea la compra).
• Protección anticobro: una validación en el checkout impide pagar un regalo que figura como regalo pero llegó con precio — el comprador nunca paga por error un artículo marcado de regalo. La validación actúa solo en el checkout, nunca mientras se navega.
• Cuando "qué cuenta" son colecciones, la barra de progreso del carrito no puede predecir la pertenencia desde el navegador y no se muestra para esa oferta; el regalo y el precio siguen siendo correctos (los decide el servidor).

10Arma tu caja (build-a-box)

El cliente llena una caja de tamaño fijo (p. ej. 3 artículos) con lo que elija de un grupo. Cada caja completa se cobra con descuento o a un precio de caja cerrado.

10.1 Configuración

10.2 Qué ve tu cliente

Usa el mismo bloque Combora mix & match y el mismo selector con contador que la sección 6: "selecciona 3", contador de progreso, CTA con cantidad. La diferencia es la matemática: aquí las cajas se cobran por caja completa — con caja de 3, seis artículos son dos cajas; siete artículos son dos cajas y un artículo a precio normal.

10.3 Detalles del tipo

• Grupo elegible: variantes, productos, colección o toda la tienda (el selector visual solo con variantes específicas, como en mix).
• El precio de caja se reparte entre los artículos de forma exacta; con monedas sin decimales (JPY) o con tres decimales (BHD) el reparto respeta la moneda.
• Admite el opt-in de suscripciones (apartado 4.5).

11Complementos (comprados juntos habitualmente)

Un producto principal sugiere productos complementarios; si el cliente se lleva el conjunto, recibe un descuento. Es el clásico "frequently bought together" de la ficha de producto.

11.1 Configuración

11.2 Qué ve tu cliente

11.3 Detalles del tipo

• El descuento se aplica cuando el principal y al menos un complemento están en el carrito; cubre las líneas del conjunto.
• El bloque también puede añadirse a la plantilla del carrito como último empujón de cross-sell.
• Los complementos agotados aparecen deshabilitados con su aviso, nunca se pre-marcan.

12Combo

El tipo avanzado: apila dos o más subofertas (de cualquiera de los otros tipos) en un solo pack. La diferencia clave con publicar packs separados: dentro de un combo las subofertas se suman — el cliente puede recibir el descuento por volumen y el regalo a la vez.

12.1 Configuración

12.2 Qué ve tu cliente

En el carrito, cada parte del combo actúa con su propia etiqueta: el descuento de volumen en sus líneas y el regalo auto-añadido a $0.00 (visible en la captura de la sección 13).

12.3 Detalles del tipo

• Las subofertas se suman dentro del combo, pero el combo compite como un todo contra los demás packs por la regla de la mejor oferta por línea.
• El regalo de una suboferta GWP usa el mismo motor auto-add que el tipo regalo.
• Límite de tamaño: el conjunto aplanado de productos del combo no puede superar 50 entradas (el editor lo muestra: "Usa X de 50").

13Combinar packs entre sí

Puedes publicar tantos packs como tu plan permita, incluso sobre los mismos productos. Las reglas de convivencia son fijas y predecibles:

1. La mejor oferta por línea. Para cada artículo del carrito, Shopify aplica la oferta que más le descuenta a ese artículo. Nunca se suman dos packs sobre la misma línea.
2. Packs distintos pueden convivir en el mismo carrito — cada uno sobre sus líneas. Un descuento mix en las tablas y un regalo por gasto pueden aplicarse a la vez porque actúan sobre líneas distintas.
3. En empate, gana el pack más antiguo (el primero que creaste).
4. La excepción es el combo: sus subofertas sí se suman entre ellas (sección 12).

Ejemplo numérico real (verificado en la tienda)

14Creación masiva

Desde la galería de Crear pack hay dos flujos para crear muchos packs de golpe. Ambos crean borradores: nada sale a la tienda hasta que revisas y publicas.

14.1 Generar desde una colección

1. Elige la colección.
2. Elige la plantilla: "Un multipack por cada producto" (un pack fijo de N unidades por cada producto) o "Un solo pack para toda la colección".
3. Configura unidades y descuento, y pulsa Crear borradores.

14.2 Importar desde un CSV

Para catálogos grandes o para migrar de otra app. La página incluye la referencia completa del formato, una plantilla descargable con un ejemplo por tipo y un botón de exportación (baja todos tus packs en el mismo formato, listo para reimportar en otra tienda).

• Tipos importables: fixed, volume, mix_and_match, build_a_box, bogo (los tipos con regalo/ancla/subofertas se crean en el editor).
• Referencias por handle de producto/colección o por GID de Shopify.
• En components (solo fixed): handle:cantidad separados por |.
• Hasta 200 filas por importación; un archivo mayor se recorta y lo avisa.

15Gestión diaria

15.1 La lista

Búsqueda por nombre, filtro por estado y, en cada fila: Duplicar (crea una copia en borrador), Publicar / Pasar a borrador y Eliminar. La fecha de cada fila es la última actualización (tooltip al pasar el cursor).

15.2 Acciones masivas

15.3 Ciclo de vida de un pack

Borrador

Invisible para la tienda. Se puede editar sin límite.

Publicado

Oferta activa (dentro de su ventana de programación). Editar no cambia nada en vivo hasta pulsar Actualizar pack.

Pasar a borrador

Retira la oferta al momento; la configuración se conserva íntegra para republicar.

Eliminar

Borra el pack y retira su descuento (y el producto padre, si era un pack fijo). No se puede deshacer. La analítica de pedidos pasados se conserva.

16Analítica

El gráfico "Pedidos con pack en el tiempo" muestra una barra por día del rango, con el valor impreso sobre las barras con datos y tooltip por barra.

17Ajustes y planes

17.1 Ajustes

• Idioma de la app: 7 idiomas (inglés, español, francés, alemán, italiano, portugués, neerlandés). Afecta al admin; lo que ve tu cliente sigue el idioma de tu tema/mercado.
• Sincronizar descuentos: re-publica el estado de todos los packs hacia Shopify y limpia descuentos antiguos. Úsalo si sospechas que algo quedó desalineado (p. ej. tras restaurar un tema). Si no había nada que arreglar, lo dice: "Todo estaba ya al día."
• Acceso para desarrolladores: los datos públicos que tu tema puede leer (anexo 20). La documentación in-app del contrato es parte del plan Plus.

17.2 Planes

Precios planos: nunca cobramos un porcentaje de tus ventas, y el precio no depende de tu plan de Shopify — una tienda Basic y una Plus pagan lo mismo.

• Gratis ($0/mes): hasta 3 packs publicados a la vez (los borradores no cuentan) con los 8 tipos incluidos. Al intentar publicar el 4º, la app lo bloquea con el aviso correspondiente: pasa otro a borrador o mejora el plan. En el plan gratis, los bloques muestran una insignia discreta "Powered by Combora".
• Pro ($14.99/mes): packs publicados ilimitados y sin insignia.
• Plus ($39.99/mes): todo lo de Pro, más soporte prioritario, importación/exportación CSV masiva (hasta 200 packs por archivo) y el acceso para desarrolladores (documentación del contrato para storefronts headless y a medida).

La facturación va por Shopify (Managed Pricing) — se gestiona y cancela desde la propia página de Planes. Las tiendas fundadoras (las primeras 100 instalaciones) conservan el producto completo gratis para siempre.

18Diagnóstico y soporte

Diagnóstico (la segunda pestaña de Ayuda) es tu primera parada cuando algo no cuadra — y lo que soporte te pedirá si abres un ticket. Combora registra automáticamente, por tienda, todo lo que falla por debajo (en el servidor y en tu tienda online) aunque el cliente nunca lo vea, y este panel lo pone a tu alcance. No guarda ningún dato de tus clientes.

18.1 Chequeos de salud

El estado en vivo de lo que soporte pregunta primero, verificado contra Shopify en cada carga:

18.2 Registro de eventos

Cada entrada es algo que pasó y quedó guardado: un fallo al publicar, un regalo que Shopify rechazó añadir (con el motivo exacto), un descuento que colisionó con otro, un webhook que falló… Filtra por nivel (Info = esperado pero relevante, como el límite del plan; Aviso; Error) y por área (publicación, descuentos, plan y facturación, tienda, sincronización…). Un registro vacío es buena señal: solo se llena cuando algo va mal. Los eventos se conservan 30 días.

18.3 El informe de soporte

Un único documento con todo lo que hace falta para diagnosticar tu tienda de una pasada: los chequeos de salud, tu plan y configuración (sin datos sensibles), el estado de publicación de cada pack y los últimos eventos. Cuando contactes con soporte, pulsa Copiar informe (o Descargar como archivo) y adjúntalo al ticket — con eso, quien te atiende ve exactamente lo que pasó sin pedirte capturas ni accesos.

• El informe no incluye datos de clientes ni claves: solo salud, configuración de packs y eventos técnicos.
• Si el botón de copiar no funciona en tu navegador, el texto queda seleccionado — pulsa Ctrl+C (Cmd+C en Mac) — o usa la descarga.

19Limitaciones y reglas importantes

La referencia única de límites, verificados contra el código de la app:

Reglas de dinero (siempre exactas)

• Los porcentajes truncan hacia abajo el descuento (nunca se redondea a favor de cobrar de más).
• Los importes y precios fijos se reparten entre líneas con resto exacto: la suma de las partes siempre iguala el total.
• Los decimales dependen de la moneda de la tienda (JPY sin decimales, BHD con tres…) — nunca se asume "2 decimales".
• El precio cobrado lo calcula Shopify en el checkout con la configuración publicada. Lo que muestran los bloques del tema es informativo.

Otras reglas

• Las suscripciones están bloqueadas en líneas de pack salvo opt-in explícito (apartado 4.5).
• El regalo de un GWP no se anuncia en la ficha del propio producto-regalo (un premio no es un gancho).
• Los packs publicados fuera de su ventana de programación no aplican descuento (se reactivan solos).

20Solución de problemas

No veo la oferta en la tienda

① ¿El pack está Publicado (no borrador) y dentro de su ventana de fechas? ② ¿Añadiste el bloque correcto a la plantilla (tarjeta "Dónde aparece" del editor)? ③ Si editaste un pack publicado, ¿pulsaste Actualizar pack?

El regalo no se añade solo

① ¿Está activado el app embed Combora Gift? ② ¿El carrito cumple la condición contando solo lo que califica (el regalo no cuenta)? ③ ¿El cliente lo quitó a mano en esta sesión? ④ ¿El regalo tiene stock?

El descuento del carrito no coincide con lo que esperaba

Recuerda la regla: solo la mejor oferta por línea. Si dos packs compiten por el mismo artículo, gana el que más descuenta (y en empate, el más antiguo). Las sumas solo ocurren dentro de un combo.

Publiqué y dice "límite del plan"

El plan Gratis permite 3 packs publicados a la vez. Pasa otro a borrador o mejora el plan.

La barra de progreso del regalo no aparece

Se muestra en la plantilla del carrito (bloque Combora gift progress) y solo para ofertas cuyo criterio puede evaluarse en el navegador; con "qué cuenta = colecciones" no se muestra, aunque el regalo funciona igual.

El selector de casillas no aparece en mix / caja

Solo se pinta cuando el grupo elegible son variantes específicas. Con colección o toda la tienda, el cliente añade productos con normalidad y el descuento entra al calificar.

Errores al importar CSV

Cada fila fallida se lista con su motivo. Corrige esas filas y vuelve a ejecutar solo con ellas — las filas buenas ya se crearon.

Sospecho que un descuento quedó "huérfano"

Ajustes → Sincronizar descuentos repara el estado. Nunca edites a mano el descuento "Combora" en la sección Descuentos de Shopify.

21Anexo para desarrolladores: el contrato público

Combora publica los datos de tus packs en tu tienda como metaobjetos y metafields con el namespace combora, con lectura pública desde el storefront. Cualquier desarrollador puede construir una UI 100% propia leyendo estos datos desde Liquid o la Storefront API — sin llamar a ninguna API de la app. Este contrato es versionado y solo-aditivo (versión actual: public.v1): los campos existentes nunca se renombran ni se retipan.

20.1 Qué se crea al instalar

La instalación aprovisiona las definiciones (los "esquemas") — visibles en Configuración → Metafields y metaobjetos y en Contenido → Metaobjetos:

• Metaobjetos: combora_bundle (el pack), combora_component (cada línea de componente) y combora_tier (cada nivel de volumen/umbral). Los tres con acceso storefront PUBLIC_READ, publicables y traducibles.
• Metafields de tienda: combora.index y combora.manifest (JSON, lectura pública).
• Metafield de producto: combora.bundles (list.metaobject_reference → combora_bundle) — el índice inverso producto → sus packs.

20.2 Qué pasa al publicar / actualizar / retirar

20.3 combora_bundle campo a campo

20.4 El descriptor eligible

Cuando el pool de un pack no enumera variantes (colección o toda la tienda), config lleva un descriptor con la misma forma en todos los tipos:

{ "mode": "all" | "products" | "collections" | "variants",
  "variants":   ["gid://shopify/ProductVariant/…"],
  "products":   ["gid://shopify/Product/…"],
  "collections":["gid://shopify/Collection/…"] }

Ojo: los hijos role:"option" de un pool por colección son una foto tomada al publicar; la pertenencia viva (y el precio) la resuelve siempre la Function en el checkout.

20.5 combora.index y combora.manifest

shop.metafields.combora.index — la tabla de ruteo de packs publicados (existe para que nunca tengas que iterar metaobjects.combora_bundle.values, que Liquid recorta a 50 en silencio):

{ "schema": 1, "revision_highwater": 128, "generated_at": "…",
  "bundles": [
    { "id": 8123, "handle": "combora-bundle-8123", "type": "fixed",
      "gid": "gid://shopify/Metaobject/…", "status": "active", "revision": 42 }
  ] }

shop.metafields.combora.manifest — el descriptor del contrato que una herramienta lee una vez: contract_version, contadores y los GIDs de las tres definiciones.

20.6 Leerlo desde Liquid

{%- comment -%} En una ficha de producto: los packs de ESTE producto {%- endcomment -%}
{%- for bundle in product.metafields.combora.bundles.value -%}
  <h3>{{ bundle.title.value | escape }}</h3>
  {%- if bundle.badge_label.value != blank -%}
    <span class="badge">{{ bundle.badge_label.value | escape }}</span>
  {%- endif -%}
  <ul>
    {%- for component in bundle.components.value -%}
      <li>{{ component.quantity.value }}× {{ component.label.value | escape }}</li>
    {%- endfor -%}
  </ul>
{%- endfor -%}

{%- comment -%} O por handle directo, en cualquier plantilla {%- endcomment -%}
{%- assign bundle = metaobjects.combora_bundle['combora-bundle-8123'] -%}

Ambas rutas son lecturas acotadas (lista propia del producto o handle directo) — jamás el .values global.

20.7 Leerlo desde la Storefront API (localizado)

query BundleByHandle @inContext(language: FR) {
  metaobject(handle: { type: "combora_bundle", handle: "combora-bundle-8123" }) {
    title:       field(key: "title")       { value }
    badge_label: field(key: "badge_label") { value }
    components:  field(key: "components") {
      references(first: 25) {
        nodes { ... on Metaobject {
          label:    field(key: "label")    { value }
          quantity: field(key: "quantity") { value }
        } }
      }
    }
  }
}

@inContext devuelve las traducciones sembradas por la app; lo no traducido cae al idioma base automáticamente.

20.8 Usos posibles

• UI de bundle 100% a medida en el tema, sin los bloques de Combora, leyendo título, badge, componentes y ahorro del metaobjeto.
• Landing de campañas: una página que lista los packs activos desde combora.index y pinta cada uno por handle.
• Headless / Hydrogen: misma lectura vía Storefront API con localización por mercado.
• Integraciones (feeds, apps de recomendación): el manifest declara la versión del contrato y dónde está todo.

20.9 Reglas para el desarrollador

• El precio es de la Function. Los campos del metaobjeto son display: no sumes discount_value de un combo ni recalcules precios en el tema — el checkout manda.
• Solo-aditivo: pueden aparecer campos nuevos; los existentes no cambian. Programa lecturas tolerantes a campos desconocidos.
• Combos: agrupa los hijos por position dividido entre 1000 (cada suboferta ocupa un tramo de 1000) o por config.of[].index — nunca por role, que puede repetirse.
• Privado ≠ contrato: los metafields $app:runtime, $app:fnvars y $app:validation del descuento son internos de las Functions, sin acceso storefront, y su forma puede cambiar sin aviso. No construyas sobre ellos.
• El detalle exhaustivo (definiciones JSON, semántica del sync, decisiones congeladas) está en docs/CONTRATO-PUBLICO.md del repositorio.

22Registro de incidencias de esta edición

Durante la elaboración del manual se probó cada flujo en una tienda real. Todo lo documentado arriba refleja el comportamiento verificado. Se detectaron dos desviaciones, anotadas aquí y pendientes de corrección (el manual describe el comportamiento correcto previsto):

Manual elaborado y verificado el 15 de agosto de 2026 sobre la tienda de desarrollo app-bundle-6pofnlbj, con compras de prueba reales (pasarela Bogus). Las capturas están en docs/manual/img/.