---
name: shopify-ticket-promedio
description: "Solo lectura: calcula el ticket promedio por día, semana o mes y lo separa entre clientes nuevos y recurrentes. Úsala cuando quieras medir si una promoción, un combo o un umbral de envío gratis subió el valor de cada pedido."
---

## Propósito
Calcula el ticket promedio (AOV, valor promedio por pedido) en periodos configurables (día, semana o mes) y separa los resultados entre clientes nuevos y recurrentes. Sigue la evolución del ticket promedio para medir el impacto de programas de venta adicional (upsell), ofertas de combos o umbrales de envío gratis. Solo lectura: no ejecuta mutaciones.

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_orders,read_customers`
- Las consultas se ejecutan con `shopify store execute`.
- Permisos de la API: `read_orders`, `read_customers`

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | texto | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| days_back | entero | no | 90 | Ventana total de días hacia atrás |
| bucket | texto | no | week | Periodo de agrupación: `day`, `week` o `month` |
| format | texto | no | human | Formato de salida: `human` o `json` |

## Seguridad

> ℹ️ Skill de solo lectura: no ejecuta mutaciones. Puedes correrla en cualquier momento.

## Pasos

1. **OPERACIÓN:** `orders` — consulta
   **Entradas:** `query: "created_at:>='<HOY - days_back días>'"`, `first: 250`; selecciona `totalPriceSet`, `customer { id, numberOfOrders }`, `createdAt` y el cursor de paginación
   **Resultado esperado:** Todos los pedidos de la ventana; pagina hasta que `hasNextPage: false`

2. Clasifica cada pedido: si `customer.numberOfOrders == 1` → pedido de cliente nuevo; si no → cliente recurrente

3. **OPERACIÓN:** `customers` — consulta (enriquecimiento opcional para dar contexto de cohortes)
   **Entradas:** Clientes recientes, para validar la separación entre nuevos y recurrentes

4. Agrupa los pedidos por periodo; calcula el ticket promedio por periodo y por segmento de cliente

## Operaciones GraphQL

```graphql
# orders:query — validada con api_version 2025-01
query AOVData($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          id
          numberOfOrders
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

```graphql
# customers:query — validada con api_version 2025-01
query NewVsReturningCustomers($query: String!, $after: String) {
  customers(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        numberOfOrders
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar la siguiente salida en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Evolución del ticket promedio        ║
║  Tienda: <dominio de la tienda>              ║
║  Inicio: <YYYY-MM-DD HH:MM UTC>              ║
╚══════════════════════════════════════════════╝
```

**Después de cada paso**, muestra:
```
[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Parámetros: <resumen breve de las entradas clave>
          → Resultado: <cantidad o desenlace>
```

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
EVOLUCIÓN DEL TICKET PROMEDIO  (<days_back> días, periodo: <bucket>)
  Pedidos analizados:          <n>
  Ticket promedio general:     $<monto>
  Ticket de clientes nuevos:   $<monto>
  Ticket de recurrentes:       $<monto>

  Periodo     Pedidos  Ticket  Nuevos   Recurrentes
  ────────────────────────────────────────────────────
  2026-W14    <n>      $<n>    $<n>     $<n>
  Archivo: aov_trends_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-ticket-promedio",
  "store": "<dominio>",
  "period_days": 90,
  "overall_aov": 0,
  "new_customer_aov": 0,
  "returning_customer_aov": 0,
  "by_period": [],
  "output_file": "aov_trends_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `aov_trends_<YYYY-MM-DD>.csv` con las columnas:
`period`, `order_count`, `aov`, `new_customer_orders`, `new_customer_aov`, `returning_orders`, `returning_aov`, `currency`

## 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 hechos como invitado | No hay ficha de cliente | Cuéntalos en los totales, pero exclúyelos de la separación entre nuevos y recurrentes |
| No hay pedidos en la ventana | Tienda nueva o periodo de pocas ventas | Termina con un ticket promedio de 0 |

## Buenas prácticas
- Si subes el umbral de envío gratis o lanzas un combo, deberías ver un aumento del ticket promedio en la semana o el mes del lanzamiento: usa este reporte para medir el impacto.
- El ticket promedio de los clientes recurrentes suele ser más alto que el de los nuevos; si la brecha se achica, puede ser señal de que la fidelidad se está debilitando.
- `bucket: week` es lo mejor para medir campañas; `bucket: month`, para seguir la tendencia de largo plazo.
- Los pedidos hechos como invitado no se pueden clasificar como nuevos o recurrentes: en tiendas con muchas compras como invitado, la separación se quedará corta en clientes nuevos.