Gift Card Liability Report

Purpose

Calculates the store's total outstanding gift card liability — the sum of unredeemed gift card balances that represent a future obligation to deliver goods. Breaks the liability down by issue-month cohort and remaining-balance band so finance can size the obligation, age it, and forecast breakage. This is the bookkeeping companion to gift-card-balance-report (which lists individual cards). Read-only — no mutations.

Prerequisites

Parameters

Safety

> ℹ️ Read-only skill — no mutations are executed. The dollar figure produced is the deferred-revenue liability for accounting purposes; review with your accountant before booking journal entries.

Liability Model

For every enabled gift card with balance > 0:

Aggregations:

Workflow Steps

Inputs: query: "status: balance:>0", first: 250, select id, balance, initialValue, createdAt, updatedAt, expiresOn, enabled, lastCharacters, pagination cursor

Expected output: All gift cards with positive balance; paginate until hasNextPage: false

GraphQL Operations

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

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Gift Card Liability Report           ║
║  Store: <store domain>                       ║
║  As of: <YYYY-MM-DD>                         ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
GIFT CARD LIABILITY  (as of <date>)
  Active cards w/ balance:   <n>
  Total outstanding:         $<amount>
  Initial value issued:      $<amount>
  Redeemed to date:          $<amount>  (<pct>%)
  Breakage candidates:       <n>  ($<amount>)

  By issue cohort (YYYY-MM):
    2024-12  Cards: <n>  Liability: $<n>
    2025-01  Cards: <n>  Liability: $<n>

  By balance band:
    ≤ $10     Cards: <n>  Liability: $<n>
    ≤ $50     Cards: <n>  Liability: $<n>
    ≤ $100    Cards: <n>  Liability: $<n>
    > $500    Cards: <n>  Liability: $<n>

  Output: gift_card_liability_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "gift-card-liability-report",
  "store": "<domain>",
  "as_of": "<YYYY-MM-DD>",
  "active_with_balance": 0,
  "total_outstanding": 0,
  "initial_value_issued": 0,
  "redeemed_to_date": 0,
  "redemption_rate_pct": 0,
  "breakage_candidates_count": 0,
  "breakage_candidates_value": 0,
  "currency": "USD",
  "by_cohort": [],
  "by_band": [],
  "output_file": "gift_card_liability_<date>.csv"
}

Output Format

CSV file gift_card_liability_.csv with columns:

gift_card_id, last_characters, initial_value, balance, redeemed, currency, created_at, issue_cohort, balance_band, updated_at, expires_on, breakage_candidate, customer_email

Error Handling

Best Practices