--- name: shopify-riesgo-abandono-clientes description: "Solo lectura: califica a tus clientes según la probabilidad de que dejen de comprar, con base en qué tan reciente fue su última compra, cómo baja su frecuencia y cada cuánto suelen volver. Úsala cuando quieras saber a quién contactar antes de perderlo." --- ## Propósito Predice qué clientes están en riesgo de dejar de comprar (abandono o churn) comparando su comportamiento reciente con su frecuencia de compra histórica. Calcula una fecha esperada de próxima compra para cada cliente recurrente y luego califica el riesgo de abandono según qué tan atrasado va. Solo lectura: no hace cambios. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_orders,read_customers`. Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: `read_orders`, `read_customers` ## Parámetros | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | store | string | sí | — | Dominio de la tienda | | days_back | integer | no | 365 | Ventana histórica (en días) para analizar los patrones de compra | | min_orders | integer | no | 2 | Pedidos mínimos para calcular el intervalo de compra (se necesitan 2 o más para medir frecuencia) | | risk_threshold | float | no | 1.5 | Múltiplo del intervalo promedio de compra a partir del cual el cliente se marca en riesgo | | format | string | no | human | Formato de salida: `human` o `json` | ## Seguridad > ℹ️ Skill de solo lectura: no ejecuta cambios. Puedes correrla en cualquier momento sin riesgo. ## Modelo de calificación del riesgo de abandono Para cada cliente con `min_orders` compras o más: 1. **Intervalo promedio de compra (IPC)** = total de días entre el primer y el último pedido / (cantidad de pedidos - 1) 2. **Días desde el último pedido (DUP)** = hoy - fecha del último pedido 3. **Índice de atraso** = DUP / IPC 4. **Puntaje de riesgo de abandono** (0-100): - Índice de atraso ≤ 1.0 → puntaje 0-20 (Activo) - Índice de atraso 1.0–1.5 → puntaje 20-50 (Enfriándose) - Índice de atraso 1.5–2.5 → puntaje 50-80 (En riesgo) - Índice de atraso > 2.5 → puntaje 80-100 (Probablemente perdido) 5. **Valor de vida del cliente (CLV)** = gasto total / antigüedad del cliente en años × años restantes esperados ## Pasos 1. **OPERACIÓN:** `orders` — query **Entradas:** `query: "created_at:>=''"`, `first: 250`, selecciona `createdAt`, `totalPriceSet`, `customer { id, email, firstName, lastName }`, cursor de paginación **Resultado esperado:** Todos los pedidos con su cliente asociado 2. Agrupa los pedidos por cliente y calcula para cada uno: - Fechas de los pedidos (ordenadas cronológicamente) - Intervalo promedio de compra - Días desde el último pedido - Gasto total - Cantidad de pedidos 3. **OPERACIÓN:** `customers` — query (enriquecimiento) **Entradas:** IDs de los clientes de los segmentos «En riesgo» y «Probablemente perdido» **Resultado esperado:** Datos de contacto, etiquetas y gasto total 4. Calcula el puntaje de riesgo de abandono y clasifica a cada cliente en un segmento 5. Estima los ingresos en riesgo = suma de (gasto anual × probabilidad de abandono) de los clientes en riesgo ## Operaciones GraphQL ```graphql # orders:query — validado con api_version 2025-01 query OrdersForChurnAnalysis($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { createdAt totalPriceSet { shopMoney { amount currencyCode } } customer { id email firstName lastName numberOfOrders } } } pageInfo { hasNextPage endCursor } } } ``` ```graphql # customers:query — validado con api_version 2025-01 query AtRiskCustomers($ids: [ID!]!) { nodes(ids: $ids) { ... on Customer { id email firstName lastName totalSpentV2 { amount currencyCode } numberOfOrders tags createdAt } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: Clientes en riesgo de irse ║ ║ Tienda: ║ ║ Inicio: ║ ╚══════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ REPORTE DE RIESGO DE ABANDONO ( días analizados) Clientes recurrentes calificados: ───────────────────────────── Activos (puntaje 0-20): (%) Enfriándose (puntaje 20-50): (%) En riesgo (puntaje 50-80): (%) ⚠️ Probablemente perdidos (80-100): (%) 🔴 Ingresos en riesgo: /año (en la moneda de la tienda) Clientes en riesgo de mayor valor: () Puntaje: Último pedido: Total histórico: Archivo: churn_risk_.csv ══════════════════════════════════════════════ ``` ## Formato de salida Archivo CSV `churn_risk_.csv` con las columnas: `customer_id`, `email`, `first_name`, `last_name`, `order_count`, `total_spent`, `avg_purchase_interval_days`, `days_since_last_order`, `overdue_ratio`, `churn_risk_score`, `risk_segment`, `expected_annual_value` ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | `THROTTLED` | Se superó el límite de solicitudes de la API | Espera 2 segundos y reintenta hasta 3 veces | | Clientes con una sola compra | No se puede calcular el intervalo | Exclúyelos de la calificación (se necesitan 2 pedidos o más) | | Pedidos de invitados | No están vinculados a un cliente | Omítelos: no se puede armar el perfil del cliente | ## Buenas prácticas - Combínala con la skill `shopify-recuperar-clientes-inactivos` para actuar sobre los segmentos «En riesgo» y «Probablemente perdido». - Úsala junto con `shopify-segmentacion-rfm` para tener una visión más completa de la salud de tus clientes. - Los clientes de alto valor que se están yendo (el 20 % que más gasta) merecen un contacto personalizado. - Exporta el segmento «En riesgo» a tu plataforma de email marketing para montar secuencias automáticas de recuperación. - Ajusta `risk_threshold` según tu tipo de producto: consumibles (1.3), moda (1.5), muebles (2.0).