shopify-admin-gift-card-balance-report

Purpose

Queries all active and partially-redeemed gift cards and reports the total outstanding gift card liability (unredeemed balances). Used for balance sheet reporting, accounting for deferred revenue, and auditing unused gift cards before they expire. Read-only — no mutations.

Prerequisites

• Authenticated Shopify CLI session: shopify store auth --store <domain> --scopes read_gift_cards
• API scopes: read_gift_cards

Parameters

Parameter	Type	Required	Default	Description
store	string	yes	—	Store domain (e.g., mystore.myshopify.com)
status	string	no	enabled	Filter by status: enabled, disabled, or all
expiring_within_days	integer	no	30	Flag gift cards expiring within this many days
format	string	no	human	Output format: human or json

Safety

ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

1. OPERATION: giftCards — query Inputs: query: "status:<status>", first: 250, pagination cursor Expected output: All matching gift cards with balance, initialValue, expiresOn, lastCharacter, usedOn; paginate until hasNextPage: false

2. Flag cards expiring within expiring_within_days

3. Aggregate: total outstanding balance (liability), count by status, total initial value issued

GraphQL Operations

# giftCards:query — validated against 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
    }
  }
}