From shopify-admin-skills
Queries Shopify returns and orders to aggregate return reasons by product and SKU, surfacing high-return-rate products and common reasons. Read-only.
How this skill is triggered — by the user, by Claude, or both
Slash command
/shopify-admin-skills:shopify-admin-return-reason-analysisThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Queries all return requests within a date window and aggregates them by return reason code, product, and SKU. Surfaces which products have the highest return rates and which reasons (wrong size, damaged, not as described, etc.) are most common. Read-only — no mutations.
Queries all return requests within a date window and aggregates them by return reason code, product, and SKU. Surfaces which products have the highest return rates and which reasons (wrong size, damaged, not as described, etc.) are most common. Read-only — no mutations.
shopify store auth --store <domain> --scopes read_orders,read_returnsread_orders, read_returns| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| store | string | yes | — | Store domain (e.g., mystore.myshopify.com) |
| days_back | integer | no | 30 | Lookback window for return requests |
| min_returns | integer | no | 3 | Minimum returns per product to include in output |
| format | string | no | human | Output format: human or json |
ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.
OPERATION: returns — query
Inputs: query: "created_at:>='<NOW - days_back days>'", first: 250, pagination cursor
Expected output: Return objects with returnLineItems { returnReason, refundableQuantity, fulfillmentLineItem { lineItem { product { title } variant { sku } } } }; paginate until hasNextPage: false
Aggregate by: return reason → product → SKU; calculate return count and % of total returns per bucket
OPERATION: orders — query (for return rate context)
Inputs: Same date window, first: 250; count total orders as denominator for return rate calculation
# returns:query — validated against api_version 2025-01
query ReturnsAnalysis($query: String!, $after: String) {
returns(first: 250, after: $after, query: $query) {
edges {
node {
id
status
createdAt
order {
id
name
}
returnLineItems(first: 50) {
edges {
node {
id
quantity
returnReason
returnReasonNote
fulfillmentLineItem {
lineItem {
product {
id
title
}
variant {
id
sku
title
}
}
}
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
# orders:query — validated against api_version 2025-01
query OrderCountForPeriod($query: String!) {
orders(first: 1, query: $query) {
pageInfo {
hasNextPage
}
}
ordersCount: orders(first: 250, query: $query) {
edges {
node {
id
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
Claude MUST emit the following output at each stage. This is mandatory.
On start, emit:
╔══════════════════════════════════════════════╗
║ SKILL: Return Reason Analysis ║
║ Store: <store domain> ║
║ 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):
══════════════════════════════════════════════
RETURN REASON ANALYSIS (<days_back> days)
Total returns: <n>
Total orders: <n>
Return rate: <pct>%
Top Reasons
─────────────────────────────────────────
Wrong size/fit <n> (<pct>%)
Not as described <n> (<pct>%)
Damaged/defective <n> (<pct>%)
Changed mind <n> (<pct>%)
Other <n> (<pct>%)
Top Products by Return Volume
─────────────────────────────────────────
<Product Title> <n> returns (<SKU>)
Output: return_reasons_<date>.csv
══════════════════════════════════════════════
For format: json, emit:
{
"skill": "return-reason-analysis",
"store": "<domain>",
"period_days": 30,
"total_returns": 0,
"total_orders": 0,
"return_rate_pct": 0,
"by_reason": [],
"by_product": [],
"output_file": "return_reasons_<date>.csv"
}
CSV file return_reasons_<YYYY-MM-DD>.csv with columns:
return_id, order_name, product_title, sku, quantity, return_reason, reason_note, created_at
| Error | Cause | Recovery |
|---|---|---|
THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times |
| No returns in window | No return requests in period | Exit with summary: 0 returns |
| Missing product/variant on line item | Deleted product | Log as "deleted product", include in reason counts |
min_returns: 10 for larger stores to focus on statistically significant patterns rather than one-off complaints.exchange-vs-refund-ratio to understand whether high-return products are recovering revenue via exchanges.npx claudepluginhub 40rty-ai/shopify-admin-skills --plugin shopify-admin-skillsCalculates true return costs by reason and product — refund dollars, restocking impact, shipping loss, and COGS write-offs. Helps prioritize operational fixes for Shopify stores.
Triages WooCommerce refunds by analyzing refund metrics, top products, and countries to produce operational diagnostics without exposing PII.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.