---
name: shopify-saldos-tarjetas-regalo
description: "Solo lectura: lista las tarjetas de regalo activas con su saldo pendiente, vencimiento y fecha de último uso para controlar lo que la tienda debe. Úsala en el cierre contable o antes de que venzan tarjetas sin usar."
---

## Propósito
Consulta todas las tarjetas de regalo activas y parcialmente redimidas, y reporta el pasivo total pendiente por tarjetas de regalo (saldos sin redimir). Sirve para el balance general, para contabilizar los ingresos diferidos y para revisar las tarjetas sin usar antes de que venzan. Solo lectura: no hace mutaciones.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) |
| status | string | no | enabled | Filtra por estado: `enabled`, `disabled` o `all` |
| expiring_within_days | integer | no | 30 | Marca las tarjetas de regalo que vencen dentro de esta cantidad de días |
| 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:** `giftCards` — consulta
   **Entradas:** `query: "status:<status>"`, `first: 250` y el cursor de paginación
   **Resultado esperado:** Todas las tarjetas de regalo que coinciden, con `balance`, `initialValue`, `expiresOn`, `lastCharacter`, `usedOn`; pagina hasta `hasNextPage: false`

2. Marca las tarjetas que vencen dentro de `expiring_within_days`

3. Consolida: saldo pendiente total (pasivo), cantidad por estado y valor inicial total emitido

## Operaciones GraphQL

```graphql
# giftCards:query — validada con api_version 2025-01
query GiftCardBalances($query: String, $after: String) {
  giftCards(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        balance {
          amount
          currencyCode
        }
        initialValue {
          amount
          currencyCode
        }
        enabled
        expiresOn
        createdAt
        lastCharacters
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

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

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Saldos de tarjetas de regalo         ║
║  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>
```

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
SALDOS DE TARJETAS DE REGALO  (en la moneda de la tienda)
  Tarjetas de regalo activas:   <n>
  Saldo pendiente total:        <monto>  (pasivo)
  Valor inicial total emitido:  <monto>
  Redimido a la fecha:          <monto>
  Vencen en <n> días:           <n> tarjetas  (<monto>)
  Archivo: gift_card_balances_<date>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-saldos-tarjetas-regalo",
  "store": "<dominio>",
  "active_count": 0,
  "total_outstanding_balance": 0,
  "total_initial_value": 0,
  "currency": "<moneda de la tienda>",
  "expiring_soon_count": 0,
  "expiring_soon_value": 0,
  "output_file": "gift_card_balances_<date>.csv"
}
```

## Formato de salida
Archivo CSV `gift_card_balances_<YYYY-MM-DD>.csv` con las columnas:
`gift_card_id`, `last_characters`, `status`, `initial_value`, `balance`, `currency`, `created_at`, `expires_on`, `customer_email`, `expiring_soon`

## 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 |
| Sin tarjetas de regalo | La tienda no ha emitido ninguna | Termina con un pasivo total de 0 |
| Tarjeta de regalo sin cliente | Se emitió sin cuenta de cliente | Muéstrala como «Anónima» |

## Buenas prácticas
- El saldo pendiente total es un **pasivo por ingresos diferidos** en tu balance general: inclúyelo en el cierre financiero mensual.
- Las tarjetas que vencen dentro de `expiring_within_days` representan una reducción próxima del pasivo: no hay que hacer nada, pero sirve para proyectar.
- Para los saldos pendientes altos, crúzalos con `shopify-niveles-gasto-clientes` para enviar campañas de recordatorio a quienes tienen tarjetas con mucho saldo.
- Combínala con `shopify-emitir-tarjetas-regalo` (skill de la categoría Conversión) para seguir en el tiempo las tarjetas emitidas frente a las redimidas.