---
name: shopify-motivos-devolucion
description: "Solo lectura: agrupa los motivos de devolución de tus pedidos para detectar problemas de calidad del producto o de cómo está publicado. Úsala cuando quieras saber qué productos se devuelven más y por qué."
---

## Propósito
Consulta todas las solicitudes de devolución dentro de un rango de fechas y las agrupa por código de motivo de devolución, producto y SKU. Muestra qué productos tienen las tasas de devolución más altas y qué motivos (talla equivocada, producto dañado, no es como se describe, etc.) son los más comunes. Solo lectura: no ejecuta mutaciones.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Por defecto | Descripción |
|-----------|------|-------------|-------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| days_back | integer | no | 30 | Cuántos días hacia atrás buscar solicitudes de devolución |
| min_returns | integer | no | 3 | Devoluciones mínimas por producto para incluirlo en el resultado |
| format | string | 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:** `returns` — consulta
   **Entradas:** `query: "created_at:>='<NOW - days_back days>'"`, `first: 250`, cursor de paginación
   **Resultado esperado:** Devoluciones con `returnLineItems { returnReason, refundableQuantity, fulfillmentLineItem { lineItem { product { title } variant { sku } } } }`; pagina hasta que `hasNextPage: false`

2. Agrupa por: motivo de devolución → producto → SKU; calcula la cantidad de devoluciones y el % del total de devoluciones en cada grupo

3. **OPERACIÓN:** `orders` — consulta (para dar contexto a la tasa de devolución)
   **Entradas:** El mismo rango de fechas, `first: 250`; cuenta el total de pedidos como denominador para calcular la tasa de devolución

## Operaciones GraphQL

```graphql
# returns:query — validado con api_version 2025-01
query ReturnsAnalysis($query: String!, $after: String) {
  returns(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        status
        createdAt
        order {
          id
          name
        }
        returnLineItems(first: 50) {
          edges {
            node {
              id
              quantity
              returnReason
              returnReasonNote
              fulfillmentLineItem {
                lineItem {
                  product {
                    id
                    title
                  }
                  variant {
                    id
                    sku
                    title
                  }
                }
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

```graphql
# orders:query — validado con api_version 2025-01
query OrderCountForPeriod($query: String!) {
  orders(first: 1, query: $query) {
    pageInfo {
      hasNextPage
    }
  }
  ordersCount: orders(first: 250, query: $query) {
    edges {
      node {
        id
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar esta salida en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Análisis de motivos de devolución    ║
║  Tienda: <dominio de la tienda>              ║
║  Inicio: <YYYY-MM-DD HH:MM UTC>              ║
╚══════════════════════════════════════════════╝
```

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

**Al terminar**, muestra:

Para `format: human` (por defecto):
```
══════════════════════════════════════════════
ANÁLISIS DE MOTIVOS DE DEVOLUCIÓN  (<days_back> días)
  Total de devoluciones:  <n>
  Total de pedidos:       <n>
  Tasa de devolución:     <pct>%

  Principales motivos
  ─────────────────────────────────────────
  Talla/ajuste equivocado   <n>  (<pct>%)
  No es como se describe    <n>  (<pct>%)
  Dañado/defectuoso         <n>  (<pct>%)
  Cambió de opinión         <n>  (<pct>%)
  Otro                      <n>  (<pct>%)

  Productos con más devoluciones
  ─────────────────────────────────────────
  <Título del producto>   <n> devoluciones  (<SKU>)
  Archivo: return_reasons_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-motivos-devolucion",
  "store": "<dominio>",
  "period_days": 30,
  "total_returns": 0,
  "total_orders": 0,
  "return_rate_pct": 0,
  "by_reason": [],
  "by_product": [],
  "output_file": "return_reasons_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `return_reasons_<YYYY-MM-DD>.csv` con las columnas:
`return_id`, `order_name`, `product_title`, `sku`, `quantity`, `return_reason`, `reason_note`, `created_at`

## 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 |
| No hay devoluciones en el rango | No hubo solicitudes de devolución en el período | Termina con el resumen: 0 devoluciones |
| Falta el producto o la variante en la línea | El producto fue eliminado | Regístralo como «producto eliminado» e inclúyelo en el conteo por motivo |

## Buenas prácticas
- Compara los productos con más devoluciones con sus descripciones e imágenes: las devoluciones por «no es como se describe» suelen indicar un problema de textos o de fotos.
- En tiendas grandes, usa `min_returns: 10` para enfocarte en patrones estadísticamente significativos y no en quejas aisladas.
- Córrela cada mes y compara un período con el anterior para ver si las mejoras en la presentación de los productos o en su calidad están reduciendo motivos de devolución específicos.
- Combínala con `shopify-cambios-vs-reembolsos` para entender si los productos con muchas devoluciones están recuperando ingresos mediante cambios.