shopify-admin-refund-rate-analysis

Name: shopify-admin-refund-rate-analysis
Author: 40RTY-ai

168stars17forks

How to install shopify-admin-refund-rate-analysis?

40rty-ai/shopify-admin-skills/shopify-admin-refund-rate-analysis

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-refund-rate-analysis

Installs into the current project.

Summary

Read-only: calculates refund rate by product, collection, or period — identifies quality and listing issues.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Analyzes orders with refunds to calculate refund rates by product, time period, and channel. Surfaces which products or product groups generate the most refund activity. Read-only — no mutations.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_orders`
6	- API scopes: `read_orders`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| days_back \| integer \| no \| 30 \| Lookback window \|
14	\| group_by \| string \| no \| product \| Breakdown: `product`, `vendor`, or `period` \|
15	\| min_orders \| integer \| no \| 5 \| Minimum orders per group to include in rate calculation \|
16	\| format \| string \| no \| human \| Output format: `human` or `json` \|
17
18	## Safety
19
20	> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.
21
22	## Workflow Steps
23
24	1. OPERATION: `orders` — query
25	Inputs: `query: "created_at:>='<NOW - days_back days>'"`, `first: 250`, select `refunds { refundLineItems }`, `lineItems`, pagination cursor
26	Expected output: All orders with refund data; paginate until `hasNextPage: false`
27
28	2. For each refunded line item: record product, vendor, quantity refunded, refund amount
29
30	3. Aggregate by `group_by`: calculate `refund_rate = refunded_units / total_units_sold × 100`
31
32	## GraphQL Operations
33
34	```graphql
35	# orders:query — validated against api_version 2025-01
36	query OrdersWithRefunds($query: String!, $after: String) {
37	orders(first: 250, after: $after, query: $query) {
38	edges {
39	node {
40	id
41	name
42	createdAt
43	lineItems(first: 50) {
44	edges {
45	node {
46	id
47	quantity
48	product {
49	id
50	title
51	vendor
52	}
53	variant {
54	id
55	sku
56	}
57	}
58	}
59	}
60	refunds {
61	id
62	createdAt
63	totalRefundedSet {
64	shopMoney {
65	amount
66	currencyCode
67	}
68	}
69	refundLineItems(first: 50) {
70	edges {
71	node {
72	quantity
73	lineItem {
74	product {
75	id
76	title
77	vendor
78	}
79	variant {
80	id
81	sku
82	}
83	}
84	}
85	}
86	}
87	}
88	}
89	}
90	pageInfo {
91	hasNextPage
92	endCursor
93	}
94	}
95	}
96	```
97
98	## Session Tracking
99
100	Claude MUST emit the following output at each stage. This is mandatory.
101
102	On start, emit:
103	```
104	╔══════════════════════════════════════════════╗
105	║ SKILL: Refund Rate Analysis ║
106	║ Store: <store domain> ║
107	║ Started: <YYYY-MM-DD HH:MM UTC> ║
108	╚══════════════════════════════════════════════╝
109	```
110
111	After each step, emit:
112	```
113	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
114	→ Params: <brief summary of key inputs>
115	→ Result: <count or outcome>
116	```
117
118	On completion, emit:
119
120	For `format: human` (default):
121	```
122	══════════════════════════════════════════════
123	REFUND RATE ANALYSIS (<days_back> days)
124	Orders analyzed: <n>
125	Orders with refunds: <n>
126	Overall refund rate: <pct>%
127	Total refunded: $<amount>
128
129	By <group_by>:
130	"<name>" Sold: <n> Refunded: <n> Rate: <pct>%
131	Output: refund_rate_<date>.csv
132	══════════════════════════════════════════════
133	```
134
135	For `format: json`, emit:
136	```json
137	{
138	"skill": "refund-rate-analysis",
139	"store": "<domain>",
140	"period_days": 30,
141	"orders_analyzed": 0,
142	"orders_with_refunds": 0,
143	"overall_refund_rate_pct": 0,
144	"total_refunded": 0,
145	"currency": "USD",
146	"output_file": "refund_rate_<date>.csv"
147	}
148	```
149
150	## Output Format
151	CSV file `refund_rate_<YYYY-MM-DD>.csv` with columns:
152	`group`, `group_name`, `total_units_sold`, `refunded_units`, `refund_rate_pct`, `total_refund_amount`, `currency`
153
154	## Error Handling
155	\| Error \| Cause \| Recovery \|
156	\|-------\|-------\|----------\|
157	\| `THROTTLED` \| API rate limit exceeded \| Wait 2 seconds, retry up to 3 times \|
158	\| No refunds in window \| Clean period \| Exit with 0% rate, expected \|
159	\| Deleted product on refund line \| Product removed after refund \| Log as "deleted product" in group \|
160
161	## Best Practices
162	- A refund rate above 5–10% on specific products typically signals a listing, quality, or expectation mismatch issue.
163	- Use `group_by: vendor` to identif

People who liked this also viewed

6 picks

Type

shopify-admin-refund-rate-analysis

168stars17forks

View on GitHub

How to install shopify-admin-refund-rate-analysis?

40rty-ai/shopify-admin-skills/shopify-admin-refund-rate-analysis

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-refund-rate-analysis

Installs into the current project.

Summary

Read-only: calculates refund rate by product, collection, or period — identifies quality and listing issues.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Analyzes orders with refunds to calculate refund rates by product, time period, and channel. Surfaces which products or product groups generate the most refund activity. Read-only — no mutations.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_orders`
6	- API scopes: `read_orders`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| days_back \| integer \| no \| 30 \| Lookback window \|
14	\| group_by \| string \| no \| product \| Breakdown: `product`, `vendor`, or `period` \|
15	\| min_orders \| integer \| no \| 5 \| Minimum orders per group to include in rate calculation \|
16	\| format \| string \| no \| human \| Output format: `human` or `json` \|
17
18	## Safety
19
20	> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.
21
22	## Workflow Steps
23
24	1. OPERATION: `orders` — query
25	Inputs: `query: "created_at:>='<NOW - days_back days>'"`, `first: 250`, select `refunds { refundLineItems }`, `lineItems`, pagination cursor
26	Expected output: All orders with refund data; paginate until `hasNextPage: false`
27
28	2. For each refunded line item: record product, vendor, quantity refunded, refund amount
29
30	3. Aggregate by `group_by`: calculate `refund_rate = refunded_units / total_units_sold × 100`
31
32	## GraphQL Operations
33
34	```graphql
35	# orders:query — validated against api_version 2025-01
36	query OrdersWithRefunds($query: String!, $after: String) {
37	orders(first: 250, after: $after, query: $query) {
38	edges {
39	node {
40	id
41	name
42	createdAt
43	lineItems(first: 50) {
44	edges {
45	node {
46	id
47	quantity
48	product {
49	id
50	title
51	vendor
52	}
53	variant {
54	id
55	sku
56	}
57	}
58	}
59	}
60	refunds {
61	id
62	createdAt
63	totalRefundedSet {
64	shopMoney {
65	amount
66	currencyCode
67	}
68	}
69	refundLineItems(first: 50) {
70	edges {
71	node {
72	quantity
73	lineItem {
74	product {
75	id
76	title
77	vendor
78	}
79	variant {
80	id
81	sku
82	}
83	}
84	}
85	}
86	}
87	}
88	}
89	}
90	pageInfo {
91	hasNextPage
92	endCursor
93	}
94	}
95	}
96	```
97
98	## Session Tracking
99
100	Claude MUST emit the following output at each stage. This is mandatory.
101
102	On start, emit:
103	```
104	╔══════════════════════════════════════════════╗
105	║ SKILL: Refund Rate Analysis ║
106	║ Store: <store domain> ║
107	║ Started: <YYYY-MM-DD HH:MM UTC> ║
108	╚══════════════════════════════════════════════╝
109	```
110
111	After each step, emit:
112	```
113	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
114	→ Params: <brief summary of key inputs>
115	→ Result: <count or outcome>
116	```
117
118	On completion, emit:
119
120	For `format: human` (default):
121	```
122	══════════════════════════════════════════════
123	REFUND RATE ANALYSIS (<days_back> days)
124	Orders analyzed: <n>
125	Orders with refunds: <n>
126	Overall refund rate: <pct>%
127	Total refunded: $<amount>
128
129	By <group_by>:
130	"<name>" Sold: <n> Refunded: <n> Rate: <pct>%
131	Output: refund_rate_<date>.csv
132	══════════════════════════════════════════════
133	```
134
135	For `format: json`, emit:
136	```json
137	{
138	"skill": "refund-rate-analysis",
139	"store": "<domain>",
140	"period_days": 30,
141	"orders_analyzed": 0,
142	"orders_with_refunds": 0,
143	"overall_refund_rate_pct": 0,
144	"total_refunded": 0,
145	"currency": "USD",
146	"output_file": "refund_rate_<date>.csv"
147	}
148	```
149
150	## Output Format
151	CSV file `refund_rate_<YYYY-MM-DD>.csv` with columns:
152	`group`, `group_name`, `total_units_sold`, `refunded_units`, `refund_rate_pct`, `total_refund_amount`, `currency`
153
154	## Error Handling
155	\| Error \| Cause \| Recovery \|
156	\|-------\|-------\|----------\|
157	\| `THROTTLED` \| API rate limit exceeded \| Wait 2 seconds, retry up to 3 times \|
158	\| No refunds in window \| Clean period \| Exit with 0% rate, expected \|
159	\| Deleted product on refund line \| Product removed after refund \| Log as "deleted product" in group \|
160
161	## Best Practices
162	- A refund rate above 5–10% on specific products typically signals a listing, quality, or expectation mismatch issue.
163	- Use `group_by: vendor` to identif

People who liked this also viewed

6 picks

Type