shopify-admin-gift-card-liability-report

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

168stars17forks

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

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

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

Installs into the current project.

Summary

Read-only: calculates total outstanding gift card balance as a financial liability, broken down by issue cohort and remaining balance band.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	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.
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	\| balance_bands \| array \| no \| `[10, 50, 100, 250, 500]` \| Upper edges of balance bands (in store currency) for distribution table \|
15	\| stale_days \| integer \| no \| 365 \| Cards untouched longer than this are flagged as breakage candidates \|
16	\| as_of \| string \| no \| today (UTC) \| ISO date for the "as of" snapshot label on the report \|
17	\| format \| string \| no \| human \| Output format: `human` or `json` \|
18
19	## Safety
20
21	> ℹ️ 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.
22
23	## Liability Model
24
25	For every enabled gift card with `balance > 0`:
26
27	1. Outstanding balance = sum of `balance.amount` (the liability)
28	2. Issue cohort = year-month of `createdAt`
29	3. Balance band = first band edge ≥ remaining balance, or `>max` for cards above the largest edge
30	4. Breakage candidate = card with `balance > 0` and (`updatedAt` older than `stale_days` ago OR `expiresOn` within next 30 days)
31
32	Aggregations:
33	- Total outstanding (overall + per cohort + per band)
34	- Card counts per cohort and per band
35	- Weighted-average days since issue
36	- Breakage candidate total — useful for revenue recognition under ASC 606 / IFRS 15 for stores in jurisdictions where breakage can be recognized
37
38	## Workflow Steps
39
40	1. OPERATION: `giftCards` — query
41	Inputs: `query: "status:<status> balance:>0"`, `first: 250`, select `id`, `balance`, `initialValue`, `createdAt`, `updatedAt`, `expiresOn`, `enabled`, `lastCharacters`, pagination cursor
42	Expected output: All gift cards with positive balance; paginate until `hasNextPage: false`
43
44	2. For each card, compute issue cohort, balance band, and breakage flag
45
46	3. Aggregate totals: overall liability, per-cohort table, per-band table, breakage candidate subtotal
47
48	4. Compute redeemed-to-date as `Σ(initialValue - balance)` for context
49
50	## GraphQL Operations
51
52	```graphql
53	# giftCards:query — validated against api_version 2025-01
54	query GiftCardLiability($query: String, $after: String) {
55	giftCards(first: 250, after: $after, query: $query) {
56	edges {
57	node {
58	id
59	balance {
60	amount
61	currencyCode
62	}
63	initialValue {
64	amount
65	currencyCode
66	}
67	enabled
68	createdAt
69	updatedAt
70	expiresOn
71	lastCharacters
72	customer {
73	id
74	displayName
75	defaultEmailAddress {
76	emailAddress
77	}
78	}
79	}
80	}
81	pageInfo {
82	hasNextPage
83	endCursor
84	}
85	}
86	}
87	```
88
89	## Session Tracking
90
91	Claude MUST emit the following output at each stage. This is mandatory.
92
93	On start, emit:
94	```
95	╔══════════════════════════════════════════════╗
96	║ SKILL: Gift Card Liability Report ║
97	║ Store: <store domain> ║
98	║ As of: <YYYY-MM-DD> ║
99	║ Started: <YYYY-MM-DD HH:MM UTC> ║
100	╚══════════════════════════════════════════════╝
101	```
102
103	After each step, emit:
104	```
105	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
106	→ Params: <brief summary of key inputs>
107	→ Result: <count or outcome>
108	```
109
110	On completion, emit:
111
112	For `format: human` (default):
113	```
114	══════════════════════════════════════════════
115	GIFT CARD LIABILITY (as of <date>)
116	Active cards w/ balance: <n>
117	Total outstanding: $<amount>
118	Initial value issued: $<amount>
119	Redeemed to date: $<amount> (<pct>%)
120	Breakage candidates: <n> ($<amount>)
121
122	By issue cohort (YYYY-MM):
123	2024-12 Cards: <n> Liability: $<n>
124	2025-01 Cards: <n> Liability: $<n>
125
126	By balance band:
127	≤ $10 Cards: <n> Liability:

People who liked this also viewed

6 picks

Type

shopify-admin-gift-card-liability-report

168stars17forks

View on GitHub

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

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

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

Installs into the current project.

Summary

Read-only: calculates total outstanding gift card balance as a financial liability, broken down by issue cohort and remaining balance band.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	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.
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	\| balance_bands \| array \| no \| `[10, 50, 100, 250, 500]` \| Upper edges of balance bands (in store currency) for distribution table \|
15	\| stale_days \| integer \| no \| 365 \| Cards untouched longer than this are flagged as breakage candidates \|
16	\| as_of \| string \| no \| today (UTC) \| ISO date for the "as of" snapshot label on the report \|
17	\| format \| string \| no \| human \| Output format: `human` or `json` \|
18
19	## Safety
20
21	> ℹ️ 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.
22
23	## Liability Model
24
25	For every enabled gift card with `balance > 0`:
26
27	1. Outstanding balance = sum of `balance.amount` (the liability)
28	2. Issue cohort = year-month of `createdAt`
29	3. Balance band = first band edge ≥ remaining balance, or `>max` for cards above the largest edge
30	4. Breakage candidate = card with `balance > 0` and (`updatedAt` older than `stale_days` ago OR `expiresOn` within next 30 days)
31
32	Aggregations:
33	- Total outstanding (overall + per cohort + per band)
34	- Card counts per cohort and per band
35	- Weighted-average days since issue
36	- Breakage candidate total — useful for revenue recognition under ASC 606 / IFRS 15 for stores in jurisdictions where breakage can be recognized
37
38	## Workflow Steps
39
40	1. OPERATION: `giftCards` — query
41	Inputs: `query: "status:<status> balance:>0"`, `first: 250`, select `id`, `balance`, `initialValue`, `createdAt`, `updatedAt`, `expiresOn`, `enabled`, `lastCharacters`, pagination cursor
42	Expected output: All gift cards with positive balance; paginate until `hasNextPage: false`
43
44	2. For each card, compute issue cohort, balance band, and breakage flag
45
46	3. Aggregate totals: overall liability, per-cohort table, per-band table, breakage candidate subtotal
47
48	4. Compute redeemed-to-date as `Σ(initialValue - balance)` for context
49
50	## GraphQL Operations
51
52	```graphql
53	# giftCards:query — validated against api_version 2025-01
54	query GiftCardLiability($query: String, $after: String) {
55	giftCards(first: 250, after: $after, query: $query) {
56	edges {
57	node {
58	id
59	balance {
60	amount
61	currencyCode
62	}
63	initialValue {
64	amount
65	currencyCode
66	}
67	enabled
68	createdAt
69	updatedAt
70	expiresOn
71	lastCharacters
72	customer {
73	id
74	displayName
75	defaultEmailAddress {
76	emailAddress
77	}
78	}
79	}
80	}
81	pageInfo {
82	hasNextPage
83	endCursor
84	}
85	}
86	}
87	```
88
89	## Session Tracking
90
91	Claude MUST emit the following output at each stage. This is mandatory.
92
93	On start, emit:
94	```
95	╔══════════════════════════════════════════════╗
96	║ SKILL: Gift Card Liability Report ║
97	║ Store: <store domain> ║
98	║ As of: <YYYY-MM-DD> ║
99	║ Started: <YYYY-MM-DD HH:MM UTC> ║
100	╚══════════════════════════════════════════════╝
101	```
102
103	After each step, emit:
104	```
105	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
106	→ Params: <brief summary of key inputs>
107	→ Result: <count or outcome>
108	```
109
110	On completion, emit:
111
112	For `format: human` (default):
113	```
114	══════════════════════════════════════════════
115	GIFT CARD LIABILITY (as of <date>)
116	Active cards w/ balance: <n>
117	Total outstanding: $<amount>
118	Initial value issued: $<amount>
119	Redeemed to date: $<amount> (<pct>%)
120	Breakage candidates: <n> ($<amount>)
121
122	By issue cohort (YYYY-MM):
123	2024-12 Cards: <n> Liability: $<n>
124	2025-01 Cards: <n> Liability: $<n>
125
126	By balance band:
127	≤ $10 Cards: <n> Liability:

People who liked this also viewed

6 picks

Type