---
name: shopify-tasa-reembolsos
description: "Solo lectura: calcula la tasa de reembolsos por producto, proveedor o periodo para detectar problemas de calidad o de fichas de producto. Úsala cuando quieras saber qué productos te están generando más devoluciones de dinero."
---

## Propósito
Analiza los pedidos con reembolsos para calcular las tasas de reembolso por producto, periodo y canal. Muestra qué productos o grupos de productos generan más reembolsos. Solo lectura: no hace cambios.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) |
| days_back | integer | no | 30 | Ventana de análisis (en días) |
| group_by | string | no | product | Desglose: `product`, `vendor` o `period` |
| min_orders | integer | no | 5 | Pedidos mínimos por grupo para incluirlo en el cálculo de la tasa |
| format | string | no | human | Formato de salida: `human` o `json` |

## Seguridad

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

## Pasos

1. **OPERACIÓN:** `orders` — query
   **Entradas:** `query: "created_at:>='<NOW - days_back days>'"`, `first: 250`, selecciona `refunds { refundLineItems }`, `lineItems`, cursor de paginación
   **Resultado esperado:** Todos los pedidos con sus datos de reembolso; pagina hasta `hasNextPage: false`

2. Para cada línea reembolsada: registra el producto, el proveedor, la cantidad reembolsada y el monto del reembolso

3. Agrupa según `group_by` y calcula `refund_rate = refunded_units / total_units_sold × 100`

## Operaciones GraphQL

```graphql
# orders:query — validado con api_version 2025-01
query OrdersWithRefunds($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        lineItems(first: 50) {
          edges {
            node {
              id
              quantity
              product {
                id
                title
                vendor
              }
              variant {
                id
                sku
              }
            }
          }
        }
        refunds {
          id
          createdAt
          totalRefundedSet {
            shopMoney {
              amount
              currencyCode
            }
          }
          refundLineItems(first: 50) {
            edges {
              node {
                quantity
                lineItem {
                  product {
                    id
                    title
                    vendor
                  }
                  variant {
                    id
                    sku
                  }
                }
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

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

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

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

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
ANÁLISIS DE TASA DE REEMBOLSOS  (<days_back> días)
  Pedidos analizados:          <n>
  Pedidos con reembolsos:      <n>
  Tasa general de reembolso:   <pct>%
  Total reembolsado:           <monto> (en la moneda de la tienda)

  Por <group_by>:
    "<nombre>"   Vendidas: <n>  Reembolsadas: <n>  Tasa: <pct>%
  Archivo: refund_rate_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-tasa-reembolsos",
  "store": "<dominio>",
  "period_days": 30,
  "orders_analyzed": 0,
  "orders_with_refunds": 0,
  "overall_refund_rate_pct": 0,
  "total_refunded": 0,
  "currency": "<moneda de la tienda>",
  "output_file": "refund_rate_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `refund_rate_<AAAA-MM-DD>.csv` con las columnas:
`group`, `group_name`, `total_units_sold`, `refunded_units`, `refund_rate_pct`, `total_refund_amount`, `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 |
| No hay reembolsos en la ventana | Periodo limpio | Termina con una tasa de 0 %; es un resultado esperado |
| Producto eliminado en una línea reembolsada | El producto se eliminó después del reembolso | Regístralo como «producto eliminado» dentro del grupo |

## Buenas prácticas
- Una tasa de reembolso por encima del 5–10 % en productos específicos suele indicar un problema en la ficha del producto, de calidad o de expectativas del cliente.
- Usa `group_by: vendor` para ver si los problemas de calidad se concentran en un proveedor específico.
- Cruza los productos con muchos reembolsos con `shopify-motivos-devolucion` para entender si el problema es la calidad, la talla equivocada o lo que el cliente esperaba.
- Córrela antes de las revisiones trimestrales con proveedores para tener conversaciones basadas en datos sobre la calidad de los productos y los contracargos.