---
name: shopify-limpiar-borradores
description: "Encuentra los borradores de pedido abiertos con más de N días y, si quieres, los elimina para despejar el admin. Úsala cuando tengas cotizaciones o pedidos manuales viejos acumulados que ya nadie va a completar."
---

## Propósito
Consulta los borradores de pedido abiertos con más antigüedad de la que configures y, opcionalmente, los elimina. Los borradores de pedido se acumulan por cotizaciones B2B abandonadas, pedidos manuales sin terminar o integraciones antiguas, y llenan el admin de ruido. Los borradores viejos también inflan las métricas de ingresos pendientes.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| older_than_days | integer | no | 30 | Elimina los borradores con más de esta cantidad de días |
| dry_run | bool | no | true | Muestra los borradores que se eliminarían sin ejecutar la mutación |
| format | string | no | human | Formato de salida: `human` o `json` |

## Seguridad

> ⚠️ `draftOrderDelete` elimina los borradores de pedido de forma permanente. Los borradores eliminados no se pueden recuperar. Ejecuta con `dry_run: true` para revisar la lista antes de aplicar cambios. Antes de eliminar, confirma que ninguno de los borradores viejos sea una cotización B2B activa que esté esperando la aprobación del cliente.

## Pasos

1. **OPERACIÓN:** `draftOrders` — consulta
   **Entradas:** `query: "status:open created_at:<='<NOW - older_than_days days>'"`, `first: 250`, cursor de paginación
   **Resultado esperado:** Borradores de pedido abiertos y viejos; pagina hasta `hasNextPage: false`

2. **OPERACIÓN:** `draftOrderDelete` — mutación
   **Entradas:** `id: <draft_order_id>`
   **Resultado esperado:** `deletedId`, `userErrors`

## Operaciones GraphQL

```graphql
# draftOrders:query — validada con api_version 2025-01
query StaleDraftOrders($query: String!, $after: String) {
  draftOrders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        status
        createdAt
        updatedAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
        }
        tags
        note
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

```graphql
# draftOrderDelete:mutation — validada con api_version 2025-01
mutation DraftOrderDelete($input: DraftOrderDeleteInput!) {
  draftOrderDelete(input: $input) {
    deletedId
    userErrors {
      field
      message
    }
  }
}
```

## Seguimiento de la sesión

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

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Limpia pedidos en borrador viejos    ║
║  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
  Borradores viejos encontrados:  <n>
  Borradores eliminados:          <n>
  Valor total despejado:          <monto>
  Errores:                        <n>
  Archivo:                        draft_cleanup_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-limpiar-borradores",
  "store": "<dominio>",
  "started_at": "<ISO8601>",
  "older_than_days": 30,
  "dry_run": true,
  "outcome": {
    "drafts_found": 0,
    "drafts_deleted": 0,
    "value_cleared": 0,
    "currency": "<moneda de la tienda>",
    "errors": 0,
    "output_file": "draft_cleanup_<fecha>.csv"
  }
}
```

## Formato de salida
Archivo CSV `draft_cleanup_<AAAA-MM-DD>.csv` con las columnas:
`draft_id`, `draft_name`, `customer_name`, `customer_email`, `created_at`, `total_value`, `currency`, `action`

## 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` al eliminar | El borrador ya se completó o se canceló | Regístralo como omitido y continúa |
| No hay borradores viejos | Todos los borradores son recientes o no hay ninguno | Termina con 0 resultados |

## Buenas prácticas
- Usa `older_than_days: 60` o más en tiendas B2B, donde las cotizaciones pueden tener ciclos de venta más largos.
- Antes de eliminar, revisa en la lista de simulación los borradores con notas o de valor alto: pueden ser cotizaciones pendientes legítimas.
- En escenarios B2B, considera excluir los borradores con la etiqueta `b2b-quote` o similares antes de ejecutar el paso de eliminación.
- Ejecútala cada mes como tarea rutinaria de orden en el admin.