shopify-admin-gift-card-balance-report

Name: shopify-admin-gift-card-balance-report
Author: 40RTY-ai

168stars17forks

How to install shopify-admin-gift-card-balance-report?

40rty-ai/shopify-admin-skills/shopify-admin-gift-card-balance-report

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-gift-card-balance-report

Installs into the current project.

Summary

Read-only: lists all active gift cards with remaining balance, expiry, and last-used date for liability tracking.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	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.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_gift_cards`
6	- API scopes: `read_gift_cards`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| status \| string \| no \| enabled \| Filter by status: `enabled`, `disabled`, or `all` \|
14	\| expiring_within_days \| integer \| no \| 30 \| Flag gift cards expiring within this many days \|
15	\| format \| string \| no \| human \| Output format: `human` or `json` \|
16
17	## Safety
18
19	> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.
20
21	## Workflow Steps
22
23	1. OPERATION: `giftCards` — query
24	Inputs: `query: "status:<status>"`, `first: 250`, pagination cursor
25	Expected output: All matching gift cards with `balance`, `initialValue`, `expiresOn`, `lastCharacter`, `usedOn`; paginate until `hasNextPage: false`
26
27	2. Flag cards expiring within `expiring_within_days`
28
29	3. Aggregate: total outstanding balance (liability), count by status, total initial value issued
30
31	## GraphQL Operations
32
33	```graphql
34	# giftCards:query — validated against api_version 2025-01
35	query GiftCardBalances($query: String, $after: String) {
36	giftCards(first: 250, after: $after, query: $query) {
37	edges {
38	node {
39	id
40	balance {
41	amount
42	currencyCode
43	}
44	initialValue {
45	amount
46	currencyCode
47	}
48	enabled
49	expiresOn
50	createdAt
51	lastCharacters
52	customer {
53	id
54	displayName
55	defaultEmailAddress {
56	emailAddress
57	}
58	}
59	}
60	}
61	pageInfo {
62	hasNextPage
63	endCursor
64	}
65	}
66	}
67	```
68
69	## Session Tracking
70
71	Claude MUST emit the following output at each stage. This is mandatory.
72
73	On start, emit:
74	```
75	╔══════════════════════════════════════════════╗
76	║ SKILL: Gift Card Balance Report ║
77	║ Store: <store domain> ║
78	║ Started: <YYYY-MM-DD HH:MM UTC> ║
79	╚══════════════════════════════════════════════╝
80	```
81
82	After each step, emit:
83	```
84	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
85	→ Params: <brief summary of key inputs>
86	→ Result: <count or outcome>
87	```
88
89	On completion, emit:
90
91	For `format: human` (default):
92	```
93	══════════════════════════════════════════════
94	GIFT CARD BALANCE REPORT
95	Active gift cards: <n>
96	Total outstanding balance: $<amount> (liability)
97	Total initial value issued: $<amount>
98	Redeemed to date: $<amount>
99	Expiring in <n> days: <n> cards ($<amount>)
100	Output: gift_card_balances_<date>.csv
101	══════════════════════════════════════════════
102	```
103
104	For `format: json`, emit:
105	```json
106	{
107	"skill": "gift-card-balance-report",
108	"store": "<domain>",
109	"active_count": 0,
110	"total_outstanding_balance": 0,
111	"total_initial_value": 0,
112	"currency": "USD",
113	"expiring_soon_count": 0,
114	"expiring_soon_value": 0,
115	"output_file": "gift_card_balances_<date>.csv"
116	}
117	```
118
119	## Output Format
120	CSV file `gift_card_balances_<YYYY-MM-DD>.csv` with columns:
121	`gift_card_id`, `last_characters`, `status`, `initial_value`, `balance`, `currency`, `created_at`, `expires_on`, `customer_email`, `expiring_soon`
122
123	## Error Handling
124	\| Error \| Cause \| Recovery \|
125	\|-------\|-------\|----------\|
126	\| `THROTTLED` \| API rate limit exceeded \| Wait 2 seconds, retry up to 3 times \|
127	\| No gift cards \| Store hasn't issued any \| Exit with 0 total liability \|
128	\| Gift card with no customer \| Issued without customer account \| Show as "Anonymous" \|
129
130	## Best Practices
131	- The total outstanding balance is a deferred revenue liability on your balance sheet — include it in monthly financial close.
132	- Gift cards expiring within `expiring_within_days` represent imminent liability reduction — no action needed, but useful for forecasting.
133	- For high-value outstanding balances, cross-reference with `customer-spend-tier-tagger` to target high-balance card holders with reminder campaigns.
134	- Pair with `gift-card-issuance` (conversion-optimization skill) to track cards issued vs. redeemed over time.

People who liked this also viewed

6 picks

Type

shopify-admin-gift-card-balance-report

168stars17forks

View on GitHub

How to install shopify-admin-gift-card-balance-report?

40rty-ai/shopify-admin-skills/shopify-admin-gift-card-balance-report

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-gift-card-balance-report

Installs into the current project.

Summary

Read-only: lists all active gift cards with remaining balance, expiry, and last-used date for liability tracking.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	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.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_gift_cards`
6	- API scopes: `read_gift_cards`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| status \| string \| no \| enabled \| Filter by status: `enabled`, `disabled`, or `all` \|
14	\| expiring_within_days \| integer \| no \| 30 \| Flag gift cards expiring within this many days \|
15	\| format \| string \| no \| human \| Output format: `human` or `json` \|
16
17	## Safety
18
19	> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.
20
21	## Workflow Steps
22
23	1. OPERATION: `giftCards` — query
24	Inputs: `query: "status:<status>"`, `first: 250`, pagination cursor
25	Expected output: All matching gift cards with `balance`, `initialValue`, `expiresOn`, `lastCharacter`, `usedOn`; paginate until `hasNextPage: false`
26
27	2. Flag cards expiring within `expiring_within_days`
28
29	3. Aggregate: total outstanding balance (liability), count by status, total initial value issued
30
31	## GraphQL Operations
32
33	```graphql
34	# giftCards:query — validated against api_version 2025-01
35	query GiftCardBalances($query: String, $after: String) {
36	giftCards(first: 250, after: $after, query: $query) {
37	edges {
38	node {
39	id
40	balance {
41	amount
42	currencyCode
43	}
44	initialValue {
45	amount
46	currencyCode
47	}
48	enabled
49	expiresOn
50	createdAt
51	lastCharacters
52	customer {
53	id
54	displayName
55	defaultEmailAddress {
56	emailAddress
57	}
58	}
59	}
60	}
61	pageInfo {
62	hasNextPage
63	endCursor
64	}
65	}
66	}
67	```
68
69	## Session Tracking
70
71	Claude MUST emit the following output at each stage. This is mandatory.
72
73	On start, emit:
74	```
75	╔══════════════════════════════════════════════╗
76	║ SKILL: Gift Card Balance Report ║
77	║ Store: <store domain> ║
78	║ Started: <YYYY-MM-DD HH:MM UTC> ║
79	╚══════════════════════════════════════════════╝
80	```
81
82	After each step, emit:
83	```
84	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
85	→ Params: <brief summary of key inputs>
86	→ Result: <count or outcome>
87	```
88
89	On completion, emit:
90
91	For `format: human` (default):
92	```
93	══════════════════════════════════════════════
94	GIFT CARD BALANCE REPORT
95	Active gift cards: <n>
96	Total outstanding balance: $<amount> (liability)
97	Total initial value issued: $<amount>
98	Redeemed to date: $<amount>
99	Expiring in <n> days: <n> cards ($<amount>)
100	Output: gift_card_balances_<date>.csv
101	══════════════════════════════════════════════
102	```
103
104	For `format: json`, emit:
105	```json
106	{
107	"skill": "gift-card-balance-report",
108	"store": "<domain>",
109	"active_count": 0,
110	"total_outstanding_balance": 0,
111	"total_initial_value": 0,
112	"currency": "USD",
113	"expiring_soon_count": 0,
114	"expiring_soon_value": 0,
115	"output_file": "gift_card_balances_<date>.csv"
116	}
117	```
118
119	## Output Format
120	CSV file `gift_card_balances_<YYYY-MM-DD>.csv` with columns:
121	`gift_card_id`, `last_characters`, `status`, `initial_value`, `balance`, `currency`, `created_at`, `expires_on`, `customer_email`, `expiring_soon`
122
123	## Error Handling
124	\| Error \| Cause \| Recovery \|
125	\|-------\|-------\|----------\|
126	\| `THROTTLED` \| API rate limit exceeded \| Wait 2 seconds, retry up to 3 times \|
127	\| No gift cards \| Store hasn't issued any \| Exit with 0 total liability \|
128	\| Gift card with no customer \| Issued without customer account \| Show as "Anonymous" \|
129
130	## Best Practices
131	- The total outstanding balance is a deferred revenue liability on your balance sheet — include it in monthly financial close.
132	- Gift cards expiring within `expiring_within_days` represent imminent liability reduction — no action needed, but useful for forecasting.
133	- For high-value outstanding balances, cross-reference with `customer-spend-tier-tagger` to target high-balance card holders with reminder campaigns.
134	- Pair with `gift-card-issuance` (conversion-optimization skill) to track cards issued vs. redeemed over time.

People who liked this also viewed

6 picks

Type