--- name: shopify-reporte-checkouts-abandonados description: "Agrupa los checkouts abandonados de un periodo por rango de valor del carrito y por hora del día (UTC). Úsala cuando quieras saber a qué hora y con qué monto de carrito tus clientes abandonan el checkout." --- ## Propósito Agrupa los datos de checkouts abandonados por rango de valor del carrito y por hora del día (UTC). Te ayuda a ver en qué momento y en qué rango de precio es más probable que los clientes abandonen el checkout. Se limita a lo que entrega la API `abandonedCheckouts`: el tipo de dispositivo y la ubicación geográfica no están disponibles en esta API y no se reportan. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_checkouts` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: `read_checkouts` ## Parámetros | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) | | format | string | no | human | Formato de salida: `human` o `json` | | dry_run | bool | no | false | Muestra las operaciones sin ejecutar mutaciones | | date_range_start | string | sí | — | Fecha de inicio en ISO 8601 (p. ej., `2025-01-01`) | | date_range_end | string | sí | — | Fecha de fin en ISO 8601 (p. ej., `2025-01-31`) | | cart_value_buckets | array | no | [0, 25, 50, 100, 250] | Lista de umbrales que definen los rangos de valor del carrito, en la moneda de la tienda (p. ej., `[0,25,50,100,250]` crea los rangos 0–25, 25–50, 50–100, 100–250 y 250+) | ## Pasos 1. **OPERACIÓN:** `abandonedCheckouts` — consulta **Entradas:** `first: 250`, `query: "created_at:>='' created_at:<=''"`, cursor de paginación **Resultado esperado:** Todos los checkouts abandonados del rango con `totalPrice` y `createdAt`; pagina hasta `hasNextPage: false`; luego agrega en memoria: (1) cantidad por rango de valor del carrito, (2) cantidad por hora del día (UTC, 0–23) ## Operaciones GraphQL ```graphql # abandonedCheckouts:query — validada con api_version 2025-04 query AbandonedCheckoutsReport($first: Int!, $after: String, $query: String) { abandonedCheckouts(first: $first, after: $after, query: $query) { edges { node { id createdAt totalPriceSet { shopMoney { amount currencyCode } } customer { defaultEmailAddress { emailAddress } } lineItems { edges { node { title quantity variant { price } } } } } } pageInfo { hasNextPage endCursor } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔════════════════════════════════════════════════╗ ║ SKILL: shopify-reporte-checkouts-abandonados ║ ║ Tienda: ║ ║ Inicio: ║ ╚════════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ RESUMEN DEL RESULTADO Total abandonados: Periodo: a Errores: 0 Archivo: ninguno ══════════════════════════════════════════════ ``` Para `format: json`, muestra: ```json { "skill": "shopify-reporte-checkouts-abandonados", "store": "", "started_at": "", "completed_at": "", "dry_run": false, "steps": [ { "step": 1, "operation": "AbandonedCheckoutsReport", "type": "query", "params_summary": " a ", "result_summary": " checkouts", "skipped": false } ], "outcome": { "total_abandoned": 0, "date_range_start": "", "date_range_end": "", "by_cart_value": [ { "range": "0 – 25", "count": 0, "pct": 0.0 } ], "by_hour_utc": [ { "hour": "00:00", "count": 0, "pct": 0.0 } ], "errors": 0, "output_file": null } } ``` ## Formato de salida Dos tablas que se muestran en pantalla (sin CSV): **Tabla 1: Abandonos por rango de valor del carrito** | Rango de valor del carrito | Checkouts abandonados | % del total | |----------------------------|-----------------------|-------------| | 0 – 25 | ... | ... | | 25 – 50 | ... | ... | | 50 – 100 | ... | ... | | 100 – 250 | ... | ... | | 250+ | ... | ... | Los montos van en la moneda de la tienda. **Tabla 2: Abandonos por hora del día (UTC)** | Hora (UTC) | Checkouts abandonados | % del total | |------------|-----------------------|-------------| | 00:00 | ... | ... | | 01:00 | ... | ... | | 02:00 | ... | ... | | ... | | | Para `format: json`, `by_cart_value` es una lista de objetos `{range, count, pct}` y `by_hour_utc` es una lista de objetos `{hour, count, pct}`. Nota: el tipo de dispositivo y la ubicación geográfica no están disponibles en la API `abandonedCheckouts` y esta skill no los reporta. ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | No llegan checkouts | No hay checkouts abandonados en el periodo | Amplía el rango de fechas o verifica el permiso `read_checkouts` | | Formato de fecha inválido | La fecha no está en ISO 8601 | Usa el formato `AAAA-MM-DD` | | Límite de solicitudes (429) | Demasiadas solicitudes paginadas | Acorta el rango de fechas o baja `first` a 100 | ## Buenas prácticas 1. En tiendas con mucho tráfico, acorta el rango a 7–14 días para obtener resultados más rápido; paginar 90 días de datos puede generar muchas llamadas a la API. 2. Los `cart_value_buckets` predeterminados, `[0,25,50,100,250]`, sirven para la mayoría de tiendas; ajusta los umbrales a la distribución de tu ticket promedio. 3. Las horas se reportan en UTC: conviértelas a la zona horaria de tu tienda antes de sacar conclusiones sobre los picos de abandono. 4. Ejecuta este reporte cada semana y compara el patrón por hora con los horarios de envío de tus promociones para encontrar oportunidades de momento. 5. El correo del cliente viene en el resultado de la consulta: combínalo con la skill `shopify-recuperar-carritos-abandonados` para actuar sobre los clientes con más probabilidad de comprar según el rango de valor de su carrito.