--- name: shopify-segmentacion-rfm description: "Solo lectura: califica a cada cliente por recencia, frecuencia y valor monetario (RFM) y lo ubica en grupos accionables como Campeones, Leales, En riesgo o Perdidos. Úsala cuando quieras saber a quién premiar, a quién recuperar y en quién no gastar." --- ## Propósito Hace un análisis RFM completo (Recencia, Frecuencia, valor Monetario) de toda tu base de clientes. Cada cliente recibe un puntaje de 1 a 5 en tres dimensiones (qué tan reciente fue su última compra, con qué frecuencia compra y cuánto gasta) y luego se clasifica en segmentos accionables: Campeones, Clientes leales, Leales potenciales, En riesgo, Hibernando y Perdidos. 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 (p. ej., mitienda.myshopify.com) | | days_back | integer | no | 365 | Ventana (en días) del historial de pedidos | | segments | integer | no | 5 | Cantidad de grupos (quintiles) por dimensión (3 o 5) | | min_orders | integer | no | 1 | Pedidos mínimos para que un cliente reciba puntaje | | tag_customers | boolean | no | false | Si es true, agrega al cliente una etiqueta con su segmento RFM (requiere el permiso write_customers) | | format | string | no | human | Formato de salida: `human` o `json` | ## Seguridad > ℹ️ Por defecto es de solo lectura. Si `tag_customers: true`, agregará etiquetas con la mutación customerUpdate: ejecuta primero con `dry_run: true`. ## Definición de los segmentos RFM | Segmento | Puntaje R | Puntaje F | Puntaje M | Descripción | |----------|-----------|-----------|-----------|-------------| | Campeones | 5 | 5 | 5 | Tus mejores clientes: compran hace poco, seguido y con gasto alto | | Clientes leales | 3-5 | 4-5 | 4-5 | Compradores constantes con buen gasto | | Leales potenciales | 4-5 | 2-3 | 2-3 | Compraron hace poco y podrían volverse leales | | Clientes nuevos | 5 | 1 | 1-2 | Acaban de hacer su primera compra | | Prometedores | 4 | 1-2 | 1-2 | Compra reciente pero poca frecuencia: cultívalos | | Necesitan atención | 3 | 3 | 3 | Promedio en todas las dimensiones: se están alejando | | A punto de dormirse | 2-3 | 2 | 2 | Recencia y frecuencia por debajo del promedio | | En riesgo | 1-2 | 4-5 | 4-5 | Fueron muy buenos clientes, pero no han comprado últimamente | | Hibernando | 1-2 | 1-2 | 1-3 | Bajos en todas las dimensiones: casi perdidos | | Perdidos | 1 | 1-2 | 1-5 | No compran desde hace muchísimo tiempo | ## Pasos 1. **OPERACIÓN:** `orders` — query **Entradas:** `query: "created_at:>=''"`, `first: 250`, selecciona `createdAt`, `totalPriceSet`, `customer { id, email, firstName, lastName, numberOfOrders }`, cursor de paginación **Resultado esperado:** Todos los pedidos de la ventana con su cliente asociado; pagina hasta terminar 2. Agrupa por cliente: - **Recencia** = días desde el último pedido - **Frecuencia** = cantidad total de pedidos en la ventana - **Monetario** = gasto total en la ventana 3. Califica cada dimensión de 1 a 5 por quintiles: - Ordena a todos los clientes por cada métrica - Divídelos en N grupos del mismo tamaño (quintiles) - Asigna los puntajes (5 = el mejor en recencia [compra más reciente], frecuencia [compra más seguido] y monetario [gasto más alto]) 4. Relaciona cada combinación de puntajes (R, F, M) con su segmento según las definiciones de arriba 5. **OPERACIÓN:** `customers` — query (enriquecimiento) **Entradas:** IDs de los clientes de cada segmento, para obtener sus datos de contacto **Resultado esperado:** Correo, nombre y etiquetas de los clientes principales de cada segmento ## Operaciones GraphQL ```graphql # orders:query — validado con api_version 2025-01 query OrdersForRFM($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { id createdAt totalPriceSet { shopMoney { amount currencyCode } } customer { id email firstName lastName numberOfOrders } } } pageInfo { hasNextPage endCursor } } } ``` ```graphql # customers:query — validado con api_version 2025-01 query CustomerDetails($query: String, $after: String) { customers(first: 250, after: $after, query: $query) { edges { node { id email firstName lastName numberOfOrders totalSpentV2 { amount currencyCode } tags createdAt } } pageInfo { hasNextPage endCursor } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: Segmentación RFM ║ ║ Tienda: ║ ║ Inicio: ║ ╚══════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ REPORTE DE SEGMENTACIÓN RFM ( días) Clientes calificados: ───────────────────────────── Campeones: (%) Gasto promedio: Clientes leales: (%) Gasto promedio: Leales potenciales: (%) Gasto promedio: En riesgo: (%) Gasto promedio: Hibernando: (%) Gasto promedio: Perdidos: (%) Gasto promedio: Principales Campeones: () R: F: M: Gasto: Principales En riesgo (candidatos a recuperar): () Último pedido: Total histórico: Archivo: rfm_segments_.csv ══════════════════════════════════════════════ ``` Los montos se expresan en la moneda de la tienda. Para `format: json`, muestra: ```json { "skill": "shopify-segmentacion-rfm", "store": "", "period_days": 365, "customers_scored": 0, "segments": { "champions": { "count": 0, "pct": 0, "avg_spend": 0 }, "loyal": { "count": 0, "pct": 0, "avg_spend": 0 }, "at_risk": { "count": 0, "pct": 0, "avg_spend": 0 }, "lost": { "count": 0, "pct": 0, "avg_spend": 0 } }, "output_file": "rfm_segments_.csv" } ``` ## Formato de salida Archivo CSV `rfm_segments_.csv` con las columnas: `customer_id`, `email`, `first_name`, `last_name`, `recency_days`, `frequency`, `monetary`, `r_score`, `f_score`, `m_score`, `rfm_segment` ## 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 | | Pedidos de invitados | Pedidos sin cliente asociado | Omítelos: no se pueden asignar a un perfil RFM | | Clientes con un solo pedido | Compradores nuevos o de una sola vez | Inclúyelos con F=1; tendrán naturalmente un puntaje bajo en frecuencia | ## Buenas prácticas - Usa `days_back: 365` en la mayoría de las tiendas para capturar los patrones de compra de temporada. Usa `days_back: 180` en moda rápida o consumibles. - Los segmentos Campeones y Clientes leales son ideales para ofertas exclusivas y campañas de acceso anticipado. - Los clientes En riesgo deberían recibir campañas de recuperación de inmediato: úsala con la skill `shopify-recuperar-clientes-inactivos`. - Exporta el segmento Perdidos a una lista de exclusión para dejar de gastar presupuesto de anuncios en ellos. - Cruza los datos con `shopify-cohortes-clientes` para ver tendencias RFM por cohorte a lo largo del tiempo. - Úsala con `shopify-niveles-gasto-clientes` para etiquetar automáticamente a los clientes según su segmento RFM.