---
name: shopify-segmento-fidelizacion
description: "Identifica a tus clientes de mayor valor por cantidad de pedidos y gasto histórico, los etiqueta y exporta una lista de contactos lista para tu programa de fidelización. Úsala cuando quieras inscribir a tus mejores clientes o preparar una campaña VIP."
---

## Propósito
Segmenta a tus clientes de mayor valor según la cantidad de pedidos y el gasto histórico total, los etiqueta en Shopify y exporta una lista lista para inscribirlos en un programa de fidelización o dirigirles una campaña VIP. Esta skill se encarga de los datos; para gestionar puntos de recompensa o enviar correos de fidelización necesitas una herramienta externa.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda |
| format | string | no | human | `human` o `json` |
| dry_run | bool | no | false | Muestra el resultado sin etiquetar |
| min_orders | integer | no | 3 | Cantidad mínima de pedidos históricos |
| min_spend | float | no | 200 | Gasto histórico mínimo (en la moneda de la tienda) |
| tag | string | no | loyalty-vip | Etiqueta que se aplica a los clientes que califican |

## Pasos

1. **OPERACIÓN:** `customers` — consulta
   **Entradas:** filtro `orders_count:>=(min_orders)`, `total_spent:>=(min_spend)`, `first: 250`, paginación
   **Resultado esperado:** Lista con `id`, `defaultEmailAddress { emailAddress }`, `firstName`, `lastName`, `ordersCount`, `totalSpentV2`; pagina hasta que `hasNextPage: false`

2. **OPERACIÓN:** `tagsAdd` — mutación
   **Entradas:** `id` del cliente y la etiqueta del parámetro `tag`
   **Resultado esperado:** Confirmación por cliente; recoge los `userErrors`

## Operaciones GraphQL

```graphql
# customers:query — validada con api_version 2025-04
query LoyaltyCustomers($first: Int!, $after: String, $query: String) {
  customers(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        defaultEmailAddress {
          emailAddress
        }
        firstName
        lastName
        ordersCount
        totalSpentV2 {
          amount
          currencyCode
        }
        tags
      }
    }
    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: shopify-segmento-fidelizacion        ║
║  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>
          → Resultado: <cantidad o desenlace>
```

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

**Al terminar**, para `format: human`:
```
══════════════════════════════════════════════
RESUMEN DEL RESULTADO
  Clientes VIP encontrados:  <n>
  Clientes etiquetados:      <n>
  Errores:                   <n>
  Archivo:                   loyalty_segment_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra el esquema JSON estándar con estas claves en `outcome`: `vip_customers_found`, `customers_tagged`, `errors`, `output_file`.

## Formato de salida
CSV `loyalty_segment_<AAAA-MM-DD>.csv` con las columnas:
`customer_id`, `email`, `first_name`, `last_name`, `orders_count`, `total_spent`, `currency`, `tag_applied`

## Manejo de errores
| Error | Causa | Solución |
|-------|-------|----------|
| `THROTTLED` | Límite de solicitudes | Espera 2 s y reintenta hasta 3 veces |
| `userErrors` en tagsAdd | ID de cliente no válido | Regístralo, omítelo y sigue |

## Buenas prácticas
- Antes de ejecutarla, revisa si los clientes ya tienen la etiqueta de fidelización: agrega `NOT tag:loyalty-vip` al filtro de la consulta para saltarte a los que ya están inscritos.
- Si no estás seguro de los umbrales, exporta y revisa la lista antes de etiquetar: usa `dry_run: true` para ver cuántos son y luego ajusta `min_orders` y `min_spend` antes de aplicar los cambios.
- Combínala con `shopify-recuperar-clientes-inactivos`: etiqueta a los clientes de alto valor que dejaron de comprar con `loyalty-vip` y con una etiqueta de recuperación para identificar a quiénes debes contactar primero.