Smart Loyalty Tiers — Documentación completa

Introducción

Smart Loyalty Tiers es un programa de fidelización completo para WooCommerce. A diferencia de la mayoría de plugins de fidelización que solo ofrecen un simple contador de puntos por compras, Smart Loyalty Tiers incluye 5 fuentes de ganancia distintas, 4 niveles VIP progresivos con recompensas concretas (envío gratis de por vida, acceso anticipado a nuevos productos, soporte prioritario), un sistema de insignias de gamificación, y la conversión de puntos en cupón WooCommerce de un solo uso.

Instalación y activación

1. Descarga el archivo ZIP smart-loyalty-tiers.zip desde tu área de cliente DataFirefly.
2. En WordPress, ve a Plugins → Añadir nuevo → Subir plugin.
3. Selecciona el ZIP y haz clic en Instalar ahora.
4. Haz clic en Activar.

Al activarse, el plugin crea automáticamente 9 tablas en base de datos (prefijo wp_slt_), inserta los 4 niveles Bronze / Silver / Gold / Platinum, inserta 10 insignias de logro por defecto, añade el endpoint loyalty a Mi cuenta de WooCommerce, y programa 2 tareas cron (expiración diaria, recálculo horario de niveles).

Configuración en 3 minutos

Tras la activación, aparece un nuevo menú Loyalty en la barra lateral de admin con 5 subpáginas: Dashboard, Niveles VIP, Miembros, Insignias, Ajustes.

Paso 1 — Tasas de ganancia (Loyalty → Ajustes)

Ajusta los valores por defecto según tu estrategia:

• Puntos por unidad monetaria gastada — por defecto: 1 (1 pt / 1 unidad)
• Puntos por reseña de producto — por defecto: 50
• Puntos por referido — por defecto: 500
• Puntos por suscripción a newsletter — por defecto: 100
• Puntos por compartido social — por defecto: 25

Paso 2 — Canje en cupón

• Tasa de canje — por defecto: 100 puntos = 1 unidad de descuento
• Umbral mínimo de canje — por defecto: 500 puntos
• Límite del cupón — por defecto: 30 % del subtotal del carrito

Paso 3 — Visualización y gamificación

• Etiqueta de puntos — por defecto: «puntos» (por ejemplo: «millas», «estrellas», «fireflies»)
• Gamificación activada — activa el overlay de celebración al subir de nivel
• Notificaciones por email — activa los emails de subida de nivel e insignia ganada

Los 4 niveles VIP

Cada cliente se asigna automáticamente a un nivel en función de su total de puntos acumulados de por vida (independientemente de los canjes). Los niveles inicializados:

• Bronze — 0 puntos, sin beneficios especiales, nivel de entrada
• Silver — 500 puntos acumulados, multiplicador x1,25 sobre puntos de compra, acceso anticipado 12h
• Gold — 2 000 puntos acumulados, multiplicador x1,5, envío gratis, soporte prioritario, acceso anticipado 24h
• Platinum — 5 000 puntos acumulados, multiplicador x2, envío gratis de por vida, acceso anticipado 48h, productos exclusivos, 500 puntos de bonus de cumpleaños

Desde Loyalty → Niveles VIP, cada nivel se edita en directo con un selector de color. Los beneficios configurables:

• Multiplicador de puntos (points_multiplier) — se aplica automáticamente a todos los puntos ganados en compras
• Envío gratis (free_shipping) — los package rates de WooCommerce se ponen a cero al calcular el carrito
• Acceso anticipado en horas (early_access_hours) — cuántas horas antes de la fecha de embargo de un producto este nivel puede verlo y comprarlo
• Soporte prioritario (priority_support) — añade una insignia naranja en los pedidos del admin e inyecta una cabecera X-Priority en los emails transaccionales
• Bonus de cumpleaños (birthday_bonus) — puntos acreditados automáticamente el día del cumpleaños del cliente (si está indicado en su perfil)
• Productos exclusivos (exclusive_products) — activa el filtrado por nivel en los productos marcados como exclusivos

Las 5 fuentes de puntos

1. Compras (PurchaseAction)

Los puntos se acreditan cuando el pedido pasa al estado completado (woocommerce_order_status_completed). El cálculo:

puntos = subtotal_sin_impuestos × puntos_por_moneda × multiplicador_nivel

El sistema es idempotente: imposible ganar dos veces sobre el mismo pedido, aunque el estado oscile. En reembolso total o parcial, los puntos se revierten automáticamente en proporción al importe reembolsado.

2. Reseñas de productos (ReviewAction)

Los puntos se acreditan cuando se publica una reseña aprobada (comment_post o transition_comment_status → approved). Una opción «Sólo comprador verificado» permite limitar las ganancias a reseñas de compradores reales (protección anti-spam).

3. Referidos (ReferralAction)

Cada usuario recibe un código de referido único y un enlace de compartido. El tracking se hace vía cookie de 30 días (configurable mediante slt_referral_cookie_days). El referidor gana sus puntos cuando su referido completa su primer pedido. Un bonus de bienvenida opcional se acredita al referido.

4. Newsletter (NewsletterAction)

Dos modos de activación:

• Casilla en checkout — gestionada automáticamente si la casilla está marcada
• Hook público — do_action('slt_newsletter_subscribed', $user_id, $email) — llámalo desde Mailchimp, Brevo, MailPoet, Klaviyo o cualquier sistema

Para un formulario nativo, usa el shortcode [slt_newsletter_form].

5. Compartidos sociales (SocialShareAction)

7 plataformas soportadas vía el shortcode [slt_share_buttons]: Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram, Email. Cada compartido se registra con un límite anti-abuso:

• Máximo 5 compartidos al día por usuario (configurable)
• Un mismo compartido (usuario, plataforma, URL) solo cuenta una vez

Las recompensas concretas

Envío gratis de por vida

Para los niveles con free_shipping: true, todos los package rates de WooCommerce se ponen a cero al calcular el carrito. Sin cupón que reintroducir, sin manipulación. Un aviso verde se muestra automáticamente en el carrito: «✨ Envío gratis — estatus VIP».

Acceso anticipado a novedades

En cada producto, una metabox «Acceso anticipado Loyalty» permite definir una fecha de embargo (_slt_embargo_until). Mientras no se alcance la fecha, el producto se vuelve:

• No comprable para los niveles por debajo del umbral configurado (filtro woocommerce_is_purchasable)
• Invisible en los listados (filtro woocommerce_product_query)

Los niveles con early_access_hours > 0 pueden ver y comprar el producto en la ventana definida antes del levantamiento público del embargo. Un banner ámbar en la ficha de producto informa a los clientes elegibles.

Soporte prioritario

Para los niveles con priority_support: true, cada pedido realizado por el cliente:

• Recibe una insignia «Priority» naranja visible en la lista de pedidos del admin (HPOS y legacy)
• Recibe una cabecera X-Priority: high inyectada en los emails transaccionales — útil para filtrar en tu helpdesk (Zendesk, Freshdesk, Help Scout, etc.)

Sistema de insignias (gamificación)

10 insignias de logro son inicializadas en la activación:

• First Purchase — primer pedido
• Regular Customer — 5 pedidos acumulados
• Power Buyer — 10 pedidos acumulados
• Reviewer — primera reseña publicada
• Critic — 10 reseñas publicadas
• Brand Ambassador — primer referido exitoso
• Influencer — 5 referidos exitosos
• Social Butterfly — 10 compartidos sociales
• Insider — suscripción a newsletter
• Big Spender — 1 000 unidades gastadas de por vida

Desde Loyalty → Insignias, edita las existentes o crea nuevas. Cada insignia tiene un criterio JSON:

{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // para triggers basados en contador
  "amount": 1000.00       // para lifetime_spend (cantidad en moneda)
}

Una insignia también puede otorgar un bonus de puntos en su desbloqueo.

Conversión de puntos en cupón

Desde Mi cuenta → Loyalty, el cliente introduce el número de puntos a convertir y hace clic en «Generar cupón». El plugin:

1. Crea un objeto WC_Coupon único y de un solo uso
2. Limita el cupón a la dirección de email del cliente
3. Fija una expiración a 30 días
4. Deduce los puntos del saldo y registra la transacción

Un límite slt_max_redemption_percent (30 % por defecto) impide que el cupón supere un porcentaje del subtotal del carrito — protección contra la dilución de margen.

Los 7 shortcodes frontend

[slt_balance]

Muestra el saldo de puntos del cliente conectado. Atributo opcional: label="miles".

[slt_balance label="fireflies"]

[slt_tier_badge]

Muestra el nombre del nivel actual en una insignia coloreada (color del nivel).

[slt_tier_badge]

[slt_progress_bar]

Barra de progreso animada hacia el siguiente nivel, con el número de puntos restantes y un efecto de shimmer.

[slt_progress_bar]

[slt_tiers_table]

Tabla comparativa de todos los niveles con sus umbrales y beneficios — perfecto para una página «Programa de fidelización».

[slt_tiers_table]

[slt_referral_link]

Muestra el enlace de referido único del cliente + botón copiar + contador de referidos exitosos.

[slt_referral_link]

[slt_share_buttons]

Botones de compartido social. Atributos:

• url — URL a compartir (por defecto: URL de la página actual)
• title — título a compartir (por defecto: título de la página)
• platforms — lista separada por comas (por defecto: todas)

[slt_share_buttons platforms="facebook,twitter,whatsapp"]

[slt_newsletter_form]

Formulario de suscripción a la newsletter con acreditación automática de puntos al suscribirse.

[slt_newsletter_form title="Únete a nuestra newsletter VIP"]

Área cliente (Mi cuenta → Loyalty)

Una nueva pestaña Loyalty se añade automáticamente después del panel de Mi cuenta de WooCommerce. El cliente encuentra allí:

• Un hero coloreado según el color de su nivel, con su saldo y estatus
• Su barra de progreso hacia el siguiente nivel
• La lista de sus beneficios actuales
• El formulario de conversión en cupón (si su saldo supera el umbral mínimo)
• La rejilla de todas las insignias (ganadas en color, bloqueadas en gris)
• Su historial completo de transacciones (últimas 25 entradas por defecto)

Dashboard admin (Loyalty → Dashboard)

El dashboard admin muestra estadísticas a 30 días:

• Total de miembros y activos en 30 días
• Puntos en circulación (suma de saldos activos)
• Puntos ganados y canjeados en 30 días
• Referidos completados en 30 días
• Distribución de miembros por nivel (barras)
• Actividad reciente (últimas 20 transacciones de todos los miembros)

Desde la página Miembros, puedes buscar un cliente, ver su saldo y nivel, y ajustar manualmente sus puntos (award o deduct) mediante un modal AJAX con justificación.

Emails transaccionales

Se envían automáticamente dos emails HTML responsive:

Subida de nivel

Enviado al alcanzar un nuevo nivel. Contiene:

• Un banner con el color del nuevo nivel y un trofeo
• La lista de los nuevos beneficios desbloqueados
• Un CTA hacia el área Loyalty

La plantilla es sobrescribible copiándola en tu-tema/smart-loyalty-tiers/emails/tier-upgrade.php.

Insignia ganada

Enviado al desbloquear una nueva insignia, con nombre, descripción y eventual bonus de puntos acreditado.

Hooks para desarrolladores

Cada acción del plugin dispara hooks para permitir la extensión sin tocar el código:

// Tras crédito de puntos
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// Tras deducción de puntos
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

// Cambio de nivel
do_action('slt_tier_upgraded', $user_id, $new_tier, $old_tier);
do_action('slt_tier_downgraded', $user_id, $new_tier, $old_tier);

// Insignia desbloqueada
do_action('slt_badge_awarded', $user_id, $badge);

// Referido exitoso
do_action('slt_referral_completed', $referrer_id, $referee_id, $order_id);

// Suscripción a newsletter (dispararlo desde tu integración)
do_action('slt_newsletter_subscribed', $user_id, $email);

Compatibilidad HPOS y bloques Cart / Checkout

El plugin declara automáticamente su compatibilidad HPOS vía FeaturesUtil::declare_compatibility(). Todas las lecturas de pedidos pasan por la API CRUD de WooCommerce (wc_get_order()) — ninguna consulta directa sobre wp_posts.

La compatibilidad con los bloques Cart y Checkout también está declarada. El envío gratis se aplica en ambos modos (clásico y bloques).

Multilingüe (Polylang y WPML)

El plugin es totalmente traducible vía load_plugin_textdomain con el textdomain smart-loyalty-tiers. Francés e inglés están incluidos, un archivo POT completo se incluye para cualquier otro idioma.

Para sitios multilingües:

• Polylang Pro — los nombres de niveles y insignias se pueden traducir mediante la interfaz Polylang String Translations
• WPML — las mismas cadenas se registran con WPML mediante icl_register_string

FAQ y resolución de problemas

Un cliente no ve sus puntos acreditados tras un pedido

Verifica que el pedido está en estado completado (el plugin no atribuye puntos en «procesando» ni «pendiente»). Si el estado es correcto, ve a Loyalty → Miembros, busca al cliente y consulta su historial.

El envío gratis no se aplica para un cliente Gold

Verifica en Loyalty → Niveles VIP que el beneficio «Envío gratis» está activado en el nivel Gold. Vacía también las cachés de sesión de WooCommerce (wc_clear_cart_cache()).

El endpoint Mi cuenta → Loyalty devuelve un 404

Ve a Ajustes → Enlaces permanentes y haz clic en «Guardar cambios» para refrescar las rewrite rules. Es necesario una sola vez tras la activación.

El cron no se dispara

En sitios con poco tráfico, el cron de WordPress puede ser irregular. Configura un verdadero cron del sistema para llamar a wp-cron.php cada 5 a 15 minutos, y desactiva el pseudo-cron en wp-config.php:

define('DISABLE_WP_CRON', true);

Un cliente reclama puntos tras un reembolso completo

Es el comportamiento normal: en reembolso total o parcial, los puntos correspondientes se deducen automáticamente. Si el cliente insiste, puedes reacreditarle manualmente los puntos vía Loyalty → Miembros → Ajustar.

¿Cómo desactivar la expiración de puntos?

En Loyalty → Ajustes, pon «Duración antes de expiración» a 0 días. Los puntos nunca se purgarán.