Detalles operativos de descuentos

Esta guía reúne la estructura del formulario de campaña (descuentos), los tipos de efecto y un mapa de capacidades frente a mecánicas retail habituales. Para apilamiento, límites y cupones, consulta las páginas enlazadas al final.

Scope de integración

Loyal Guru admite dos scopes de integración para descuentos. El scope activo se define a nivel de Company (configurations.apply_discounts) y puede sobreescribirse por transacción mediante el flag apply_discounts en el payload de la petición.

Scope	apply_discounts	Qué hace LG en el checkout
LG como motor promocional	true (por defecto)	Evalúa campañas, calcula el descuento y modifica los valores de las líneas del carrito en la respuesta. El TPV aplica directamente los precios devueltos.
Cliente como motor promocional	false	Evalúa campañas y devuelve los IDs/códigos de descuento aplicables, pero no modifica los valores de las líneas del carrito. El TPV o el sistema de e-commerce aplica los importes.

Cuando apply_discounts: false, la respuesta de GET /discounts incluye campos adicionales para TPV (product_ids_rule_*, locations_*, location_codes) rellenos para reglas que usen categorías con taxonomía interna, permitiendo al cliente hacer el matching de productos y tiendas — ver Campos para TPV.

info

El resto de esta guía describe el scope LG como motor promocional (apply_discounts: true). Cuando apply_discounts: false, LG devuelve IDs/códigos aplicables sin modificar los valores de línea; el sistema cliente aplica los importes.

Estructura de campaña

Cada campaña de descuento se construye con el mismo conjunto de secciones. A continuación, la referencia de opciones por sección.

Sección 1: Descripción

Campo	Requerido	Por defecto	Descripción
Nombre	Sí	—	Nombre interno de la campaña
Descripción	No	—	Notas internas
Fechas de disponibilidad	Sí	Siempre activa	Ventana activa de la campaña
Tipo de recurrencia	Sí	Diaria	Diaria, semanal, mensual o último día del mes
Días disponibles	Condicional	—	Requerido si la recurrencia es semanal o mensual
Categoría	Sí	—	La categoría de campaña a la que pertenece
Imagen	No	—	Visual que se muestra a los clientes

Sección 2: Evento

El evento define qué acción del cliente activa la evaluación de esta campaña.

Evento	Descripción
Carrito	Una compra enviada por API (after_create_activity). Opción por defecto
Evento personalizado	Una entidad personalizada enviada por API. Requiere seleccionar una definición de entidad
Trigger	Un trigger nombrado enviado por API. Requiere seleccionar un trigger
Challenge	Completar un challenge. Requiere seleccionar al menos un challenge

El tipo de evento determina qué efectos, distribuciones y opciones de apilamiento están disponibles.

Sección 3: Audiencia

Opción	Descripción
Todos los clientes	Aplica a cualquier cliente, incluidos los no inscritos en el programa
Loyalty members	Solo miembros del programa. Subfiltros opcionales: países de registro, tiers, propiedades del cliente
Targeted	Una audiencia específica, enviada mediante una campaña de envío dirigido

Las campañas dirigidas (targeted) tienen siempre coupon_required = true.

Sección 4: Condiciones de victoria

Definen qué debe contener la transacción para que la campaña se aplique. Lógica AND por defecto. En condiciones de línea se soportan subgrupos con lógica AND/OR.

Condiciones de carrito

Condición	Subcondiciones
Producto (por ID/código)	Cantidad, total, total neto (>=, <=, <, >)
Producto (del catálogo)	Cantidad, total, total neto
Categoría de producto	Cantidad, total, total neto
Tienda	—
Categoría de tienda	—
País (tienda de compra)	—
Total del carrito	>=, <=, <, >
Método de pago	—

Subgrupos AND/OR para condiciones de línea: puedes combinar varias condiciones de línea con AND/OR. Ejemplo: (producto A O producto B) Y país = ES.

Condiciones de evento personalizado

Condiciones sobre atributos de la entidad personalizada. Solo un bloque de evento personalizado por campaña. Los atributos de texto también soportan el operador Not equals.

Condiciones de trigger

Condición	Descripción
Tienda	Ubicaciones concretas
Categoría de tienda	Categorías de tienda

Condiciones de challenge

Debe seleccionarse al menos un challenge. Solo un bloque de challenge por campaña.

Condiciones adicionales (todos los tipos de evento)

Condición	Descripción
País de registro del cliente	País de alta
Tier del cliente	Nivel de tier actual
Propiedades del cliente	Atributos personalizados
Atributos calculados	Atributos calculados en tiempo real
Atributos de línea	Campos personalizados en líneas
Atributos del ticket	Campos personalizados en el ticket
Canal de comunicación	Canal de interacción

Sección 5: Aplicación

Restringe a qué artículos se aplica el efecto dentro de una transacción calificada. Si está vacío, el efecto aplica a todos los artículos calificados.

Filtro	Disponible para
Producto (por ID/código)	Carrito, evento personalizado
Producto (del catálogo)	Carrito, evento personalizado
Categoría de producto	Carrito, evento personalizado

Para efectos porcentaje y ratio, la sección de aplicación es obligatoria.

Triggers y challenges no tienen sección de aplicación.

Sección 6: Efectos

El efecto define qué recibe el cliente. Los disponibles dependen del tipo de evento:

Efecto	Carrito	Trigger	Evento personalizado	Challenge
percentage	✓	—	✓	—
ratio	✓	—	✓	—
direct_value	✓	✓	✓	✓
strikethrough	✓	—	—	—
combo_price	✓	—	—	—
formula (externo)	✓	—	—	—

Las descripciones completas están en Efectos de campaña más abajo.

Sección 7: Distribución

Cómo se reparte el efecto entre líneas:

Distribución	Uso	Notas
total	Todos los efectos (por defecto)	Efecto al total de la transacción
individual_items	Todos los efectos	Línea a línea
individual_items_pro_rata	Todos salvo strikethrough	Reparto proporcional

Restricciones:

• strikethrough → solo individual_items
• combo_price → solo total o individual_items_pro_rata
• formula → solo individual_items

Para trigger, evento personalizado y challenge: solo total.

Sección 8: Límites de efecto y bundles

Solo para eventos de carrito con efectos percentage, direct_value o combo_price.

Opción	Descripción
Límite de efecto (limits)	Veces máximas que el efecto puede aplicar por transacción (0 = sin límite). Con bundle, cada aplicación suele ser un grupo bonificado (p. ej. limits: 2 = máximo 2 grupos 2x1 en el ticket)
Bundle / grupo (rule_group)	Activa agrupación: el motor forma grupos según la quantity en rule_conditions (tamaño del grupo, ej. 2 para 2x1) y aplica el beneficio sobre la quantity en rule_application (unidades bonificadas por grupo, ej. 1). Requiere alinear producto/categoría entre condiciones, aplicación y efecto

Guía para integraciones con ejemplo 2x1: Lectura desde GET — Mecánica bundle.

Sección 9: Apilamiento (stackability)

Configuración	Disponible para	Comportamiento
Stackable (+ prioridad)	Solo carrito	La campaña se apila con otras stackable en orden de prioridad
Highest Discount	Solo carrito	Solo la campaña con mayor descuento en esa categoría
Siempre Stackable, prioridad 1	Trigger, evento personalizado, challenge	Fijo; no configurable

strikethrough y combo_price requieren siempre Highest Discount.

Más detalle: Apilamiento.

Sección 10: Límites de victoria

Límite	Requerido	Descripción
Posibilidades de acumulación	Sí (por defecto: siempre)	Frecuencia: siempre, N por día/mes/año, total N
Presupuesto	No	Valor máximo total (puntos o descuento) que la campaña puede otorgar por período
Límite por transacción	No	Valor máximo por transacción individual

Más detalle: Límites.

---

Efectos de campaña

Un efecto de campaña define qué recibe el cliente cuando se aplica la campaña. El motor soporta seis tipos. La disponibilidad depende del evento (carrito, trigger, evento personalizado o challenge).

Tabla de compatibilidad

Efecto	Carrito	Trigger	Evento personalizado	Challenge
percentage	✓	—	✓	—
ratio	✓	—	✓	—
direct_value	✓	✓	✓	✓
strikethrough	✓	—	—	—
combo_price	✓	—	—	—
formula (externo)	✓	—	—	—

Porcentaje (percentage)

Descuento porcentual sobre artículos calificados u otorga un porcentaje del valor como saldo de loyalty.

Parámetro	Descripción
Valor	Porcentaje > 0. Decimales permitidos (p. ej. 0,8 = 0,8 %)
Distribución	total, individual_items o individual_items_pro_rata
Bundle/grupo	Soportado

Caso de uso: 15 % en categoría «Calzado» si el total supera €100.

Ratio

Importe fijo de saldo (puntos o wallet) por unidad monetaria gastada.

Parámetro	Descripción
Unidad	Unidad monetaria de referencia (≥ 1). Ej.: 1 = por cada €1 gastado
Valor	Saldo por unidad. Entero en modo points; decimal en modo money
Distribución	total, individual_items o individual_items_pro_rata

Casos de uso: 2 puntos por €1 en selección; €0,05 de wallet por €1 gastado.

Valor directo (direct_value)

Importe fijo de saldo o descuento fijo.

Parámetro	Descripción
Valor	Entero en points; decimal en money
Distribución	total, individual_items o individual_items_pro_rata
Bundle/grupo	Soportado

Casos de uso: 200 puntos al completar un challenge; €5 de dto. si el carrito supera €50.

Tachado (strikethrough)

Sustituye el precio de la línea en el ticket por el precio promocional del mapa strikethrough_data. El descuento aplicado es precio en ticket − precio promocional (p. ej. ticket 3 €, promo 1 € → dto. 2 €, línea a 1 €).

Parámetro	Descripción
strikethrough_data	Mapa clave → precio promocional. Clave = product_id o product_code según la compañía (debe coincidir con el identificador en la línea del ticket)
Distribución	Siempre individual_items
Apilamiento	Siempre Highest Discount

Caso de uso: precio fijo promocional por producto en caja (p. ej. producto a 1 € aunque el ticket traiga precio 3 €).

Precio combo (combo_price)

Precio combinado para un grupo de productos (bundle).

Parámetro	Descripción
Valor	Precio total del bundle > 0
Distribución	total o individual_items_pro_rata
Apilamiento	Siempre Highest Discount

Caso de uso: 3 artículos de la categoría por €29,99.

Fórmula / efecto promocional externo (formula)

Descuento a partir de un atributo de línea enviado por un sistema externo (precio promo precalculado).

Parámetro	Descripción
Fórmula	Fija: lines.total - lines.attributes.promoPrice
Distribución	Siempre individual_items
Bundle/grupo	Siempre false
Apilamiento	Stackable o Highest Discount (configurable)

Flujo: el sistema externo envía promoPrice por línea; el motor calcula dto. = total línea − promoPrice; si ≤ 0 en una línea, no aplica ahí.

Distribuciones (resumen)

Distribución	Comportamiento
total	Un solo valor al total
individual_items	Por línea calificada
individual_items_pro_rata	Reparto proporcional por valor de línea

Restricciones: como en la sección 7; trigger / evento personalizado / challenge → solo total.

---

Capacidades de campaña

Esta sección relaciona mecánicas retail habituales con el motor: totalmente soportadas, parcialmente (workaround) o no soportadas.

Para ejemplos de API, consulta Ejemplos de campañas.

Totalmente soportadas

Mecánicas de descuento — producto y línea

Mecánica	Cómo configurarla
2x1 (mismo producto)	percentage: 50, individual_items, cantidad >= 2 en el producto
3x2 en categoría	percentage: 33.33, individual_items, cantidad >= 3 en la categoría
50 % en la N.ª unidad	percentage: X repartido entre N unidades (ahorro equivalente). Ver ejemplos
% en un producto	percentage + aplicación en el producto
% en categoría	percentage + aplicación en la categoría
Descuento fijo en cesta	direct_value, distribution: total, condición total_cart >= X
Bundle: 3 unidades por €X	combo_price, cantidad >= 3, individual_items_pro_rata
Bundle cruzado A + B por €X	combo_price, condición OR en líneas, distribution: total
Cross-category: compra A, dto. en B	Condición sobre A; aplicación restringida a categoría B
Precio promocional fijo por producto	strikethrough con strikethrough_data (sustituye precio de línea; dto. = ticket − promo)
Motor externo de precios	formula con atributo promoPrice

Mecánicas de descuento — contexto y audiencia

Mecánica	Cómo configurarla
Dto. por método de pago	Condición payment_method + percentage
Dto. por tier	Condición customer_tier + percentage
Promo por país	Condición country (tienda)
Promo por tienda	Condición store o store_category
Dto. de bienvenida	Trigger after_create_profile + direct_value o percentage
Dto. de cumpleaños	Trigger birthday + percentage o direct_value
Campaña con cupón exclusivo	Audiencia targeted + coupons_desired en compra
Campaña con audiencia específica	Audiencia targeted con definición de audiencia

Puntos y wallet

Mecánica	Cómo configurarla
Puntos fijos en compra	direct_value, total, evento carrito
Ratio (2 pts/€1)	ratio, unit: 1, carrito
Multiplicador en categoría	ratio + aplicación en categoría
Puntos de bienvenida	after_create_profile + direct_value
Bonus cumpleaños	birthday + direct_value
Referidos	refer_a_friend + direct_value
Recompensa de reto	challenge + direct_value
Evento personalizado	after_create_custom_entity + direct_value
Cashback en wallet	ratio con accrual_mode money

Parcialmente soportadas (workaround)

Mecánica	Limitación	Workaround
Dto. escalonado por gasto	Una campaña, varios umbrales	Una campaña por tramo, misma categoría Highest Discount. Ver ejemplo 6
Dto. primera compra	Sin condición nativa	calculated_attribute de recuento de transacciones
BOGO cruzado (B gratis)	Dto. máx. ~50 % por línea	Hasta 50 % en B con A en carrito; 100 % gratis no nativo
Reto multi-ticket	Objetivos entre tickets separados	Roadmap; hoy condiciones en mismo periodo de evaluación
Apilado >50 % por artículo	Tope acumulado 50 %	Diseñar categorías para no superar 50 %
Recompensa en N.ª compra	Sin contador nativo	calculated_attribute (p. ej. módulo 10)

No soportadas

Mecánica	Motivo
Producto regalo / gratis en motor	No gestiona fulfillment ni añade líneas al carrito
Flash sale por franja horaria	Disponibilidad por fecha, no intradía
Dto. en envío	Sin coste de envío en el modelo de transacción
Rifa / sorteo	Sin probabilidad en el motor
Recompensa por redes sociales	Sin eventos de RRSS
Pricing dinámico interno por demanda	No calcula demanda; formula acepta precios externos
Precio por suscripción	Sin entidad suscripción; usar externo + formula

Diagrama resumen

Páginas relacionadas

• Efectos de campaña
• Estructura de campaña
• Apilamiento
• Ejemplos de campañas