← Volver al catálogo

🏷️ LTV Tagger (segmentación de clientes)

Archivo: agentes/marketing/ltv-tagger.ts · Plist: _(ninguno)_ · Horario: Diseñado para diario 02:00; hoy se ejecuta manualmente (no hay plist cargado)

Qué hace

Clasifica a todos los clientes de Shopify por su valor de vida (LTV) y les añade tags para poder segmentar campañas de email. Las categorías son: VIP (>500€ y 3+ pedidos), Recurrente (2+ pedidos), Cliente (1 pedido), Prospecto (sin compra) y COD-only (solo pedidos contra reembolso sin ninguno pagado, marcado como riesgo). Estos tags los consume luego el digest semanal para segmentar a quién enviar.

Cómo funciona

1. Carga .env y estado en data/ltv-tagger-state.json.

2. Pagina TODOS los clientes (Link header).

3. Por cliente: lee total_spent y orders_count; si tiene pedidos consulta customers/{id}/orders para contar los paid y detectar COD-only (todos gateway cod/cash y 0 pagados).

4. classify() decide el tag ltv_*. Quita los otros tags ltv_ previos y aplica el correcto con PUT /customers/{id} si cambió. Throttle suave (~2/s).

5. Guarda contadores en estado (historial 30) y notifica (sales_ltv_segment).

Datos/APIs

  • Shopify Admin API (2024-10): customers, customers/{id}/orders (read + PUT tags).
  • notify-router → evento sales_ltv_segment.
  • Vars .env: SHOPIFY_STORE, SHOPIFY_ACCESS_TOKEN.

Cómo probarlo

cd /Users/user/rifai-agents && npx tsx agentes/marketing/ltv-tagger.ts

Espera: nº de clientes cargados, desglose por segmento (VIP/Recurrente/Cliente/Prospecto/COD-only) y "Tags actualizados: N". Escribe tags reales en los clientes de Shopify.

Si se rompe / recuperar

  • Sin plist. Para programar a las 02:00 crear com.rifai.ltv-tagger y launchctl load ~/Library/LaunchAgents/com.rifai.ltv-tagger.plist.
  • Logs: stdout (redirigir a /Users/user/rifai-agents/logs/ltv-tagger.log).
  • Estado: data/ltv-tagger-state.json.

Cómo replicarlo

  • Parser .env + paginación de clientes.
  • Función classify(totalSpent, ordersCount, paidOrders, codOnly) con umbrales (500€/3, 2, 1, 0).
  • Limpieza idempotente de tags ltv_* antes de aplicar el nuevo.
  • Estado JSON con contadores + notify-router. Los tags habilitan segmentación en email-weekly-digest.