---
name: shopify-niveles-gasto-clientes
description: "Calcula cuánto ha gastado cada cliente en total y le pone una etiqueta de nivel (Bronce, Plata, Oro o Platino) según umbrales que tú defines. Úsala cuando quieras segmentar clientes VIP sin instalar una app de fidelización."
---

## Propósito
Consulta todos los clientes, calcula su gasto total a partir del historial de pedidos y les asigna una etiqueta de nivel de gasto (Bronce/Plata/Oro/Platino por defecto). Permite segmentar clientes VIP para programas de fidelización, ofertas exclusivas y atención prioritaria sin una app de fidelización de terceros. Amplía la skill `shopify-segmento-fidelizacion` con un paso que escribe en la tienda.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) |
| tiers | object | no | ver abajo | Umbrales de gasto por nivel (en la moneda de la tienda) |
| tag_prefix | string | no | tier | Prefijo de la etiqueta (p. ej., `tier:bronze`, `tier:silver`) |
| remove_old_tiers | bool | no | true | Quita las etiquetas de nivel existentes antes de aplicar las nuevas |
| dry_run | bool | no | true | Muestra una vista previa sin ejecutar mutaciones |
| format | string | no | human | Formato de salida: `human` o `json` |

Niveles por defecto (en la moneda de la tienda):
```
bronze:   0–249
silver:   250–999
gold:     1000–4999
platinum: 5000+
```

## Seguridad

> ⚠️ `tagsAdd` agrega etiquetas a las fichas de clientes que ve tu equipo y que usan los segmentos de marketing. Si `remove_old_tiers: true`, las etiquetas de nivel existentes que coincidan con `tag_prefix` se quitan antes de aplicar las nuevas. Ejecuta con `dry_run: true` para revisar cómo quedan repartidos los niveles antes de confirmar.

## Pasos

1. **OPERACIÓN:** `customers` — consulta
   **Entradas:** `first: 250`, selecciona `id`, `amountSpent` y el cursor de paginación
   **Resultado esperado:** Todos los clientes con su gasto total; pagina hasta `hasNextPage: false`

2. Asigna un nivel a cada cliente comparando `amountSpent.amount` con los umbrales de `tiers`

3. **OPERACIÓN:** `orders` — consulta (opcional, para verificar las cifras de gasto)

4. **OPERACIÓN:** `tagsAdd` — mutación
   **Entradas:** `id` del cliente, `tags: ["<tag_prefix>:<tier>"]`
   **Resultado esperado:** Etiquetas del cliente actualizadas; `userErrors`

## Operaciones GraphQL

```graphql
# customers:query — validada con api_version 2025-01
query CustomerSpendLevels($after: String) {
  customers(first: 250, after: $after) {
    edges {
      node {
        id
        displayName
        defaultEmailAddress {
          emailAddress
        }
        amountSpent {
          amount
          currencyCode
        }
        numberOfOrders
        tags
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

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

```graphql
# tagsAdd:mutation — validada con api_version 2025-01
mutation TagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Niveles de cliente por gasto         ║
║  Tienda: <dominio de la tienda>              ║
║  Inicio: <AAAA-MM-DD HH:MM UTC>              ║
╚══════════════════════════════════════════════╝
```

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

Si `dry_run: true`, antepón `[SIMULACIÓN]` a cada paso de mutación y no lo ejecutes.

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
RESUMEN DEL RESULTADO
  Clientes procesados:  <n>
  Bronce:    <n>  (<pct>%)
  Plata:     <n>  (<pct>%)
  Oro:       <n>  (<pct>%)
  Platino:   <n>  (<pct>%)
  Etiquetas aplicadas: <n>
  Errores:             <n>
  Archivo:             tier_tagging_<date>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-niveles-gasto-clientes",
  "store": "<dominio>",
  "started_at": "<ISO8601>",
  "dry_run": true,
  "tier_distribution": { "bronze": 0, "silver": 0, "gold": 0, "platinum": 0 },
  "tags_applied": 0,
  "errors": 0,
  "output_file": "tier_tagging_<date>.csv"
}
```

## Formato de salida
Archivo CSV `tier_tagging_<YYYY-MM-DD>.csv` con las columnas:
`customer_id`, `name`, `email`, `lifetime_spend`, `currency`, `tier`, `previous_tags`, `new_tags`

## 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 |
| `userErrors` en tagsAdd | ID de cliente inválido | Registra el error, omite el cliente y continúa |
| Sin clientes | Tienda vacía | Termina con 0 resultados |

## Buenas prácticas
- Ejecútala cada mes para mantener los niveles al día: los clientes que aumenten su gasto subirán de nivel automáticamente.
- Usa `remove_old_tiers: true` para que cada cliente tenga exactamente una etiqueta de nivel en todo momento.
- Ajusta los umbrales de `tiers` al ticket promedio y al valor de vida del cliente de tu tienda: los valores por defecto sirven para tiendas con un ticket promedio de 50 a 100 en la moneda de la tienda.
- Después de etiquetar, crea segmentos de clientes en Shopify con filtros por etiqueta para dirigirte a cada nivel en tus campañas de correo.