From shopify-admin-skills
Tracks Shopify return resolutions as percentages of exchanges (revenue retained), refunds (lost), and store credit (deferred) to measure revenue recovery over time or vs prior periods.
npx claudepluginhub 40rty-ai/shopify-admin-skills --plugin shopify-admin-skillsThis skill uses the workspace's default tool permissions.
Analyzes return resolutions to calculate the split between exchanges (revenue retained), store credit (revenue deferred), and refunds (revenue lost). Tracks this as a revenue recovery metric over time. Read-only — no mutations.
Aggregates Shopify return reasons by product, SKU, and reason code to identify high-return items and issues like damage or wrong size over a date window.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Analyzes return resolutions to calculate the split between exchanges (revenue retained), store credit (revenue deferred), and refunds (revenue lost). Tracks this as a revenue recovery metric over time. 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 resolutions |
| compare_days_back | integer | no | 0 | Optional prior period for comparison (0 = no comparison) |
| 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: Returns with refunds { totalRefundedSet }, exchangeLineItems, and resolution status
Categorize each return resolution:
exchangeLineItems with quantity > 0refunds with gift card or store credit paymentOPERATION: orders — query (if compare_days_back > 0)
Inputs: Same logic for prior period to compute trend
# returns:query — validated against api_version 2025-01
query ReturnResolutions($query: String!, $after: String) {
returns(first: 250, after: $after, query: $query) {
edges {
node {
id
status
createdAt
totalQuantity
order {
id
name
}
exchangeLineItems(first: 10) {
edges {
node {
id
quantity
lineItem {
variant {
id
title
}
}
}
}
}
refunds(first: 5) {
id
totalRefundedSet {
shopMoney {
amount
currencyCode
}
}
}
returnLineItems(first: 20) {
edges {
node {
refundableQuantity
returnReason
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
# orders:query — validated against api_version 2025-01
query OrdersInPeriod($query: String!, $after: String) {
orders(first: 250, after: $after, query: $query) {
edges {
node {
id
name
totalPriceSet {
shopMoney {
amount
currencyCode
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
Claude MUST emit the following output at each stage. This is mandatory.
On start, emit:
╔══════════════════════════════════════════════╗
║ SKILL: Exchange vs Refund Ratio ║
║ 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):
══════════════════════════════════════════════
EXCHANGE vs REFUND RATIO (<days_back> days)
Total returns resolved: <n>
Resolution breakdown:
Exchange (revenue kept): <n> (<pct>%)
Store credit (deferred): <n> (<pct>%)
Refund (revenue lost): <n> (<pct>%)
Revenue recovery rate: <pct>%
(exchanges + store credit as % of all returns)
Output: exchange_refund_ratio_<date>.csv
══════════════════════════════════════════════
For format: json, emit:
{
"skill": "exchange-vs-refund-ratio",
"store": "<domain>",
"period_days": 30,
"total_returns": 0,
"exchanges": { "count": 0, "pct": 0 },
"store_credit": { "count": 0, "pct": 0 },
"refunds": { "count": 0, "pct": 0 },
"revenue_recovery_rate_pct": 0,
"output_file": "exchange_refund_ratio_<date>.csv"
}
CSV file exchange_refund_ratio_<YYYY-MM-DD>.csv with columns:
return_id, order_name, resolution_type, exchange_sku, refund_amount, currency, created_at
| Error | Cause | Recovery |
|---|---|---|
THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times |
| No resolved returns in window | No completed returns in period | Exit with summary: 0 returns |
| Exchange line items empty but status indicates exchange | In-progress exchange | Count as pending, exclude from ratio |
compare_days_back to track whether returns policy changes (e.g., "exchange only" periods) improved the recovery rate.return-reason-analysis — high "wrong size" return reasons paired with low exchange rates may indicate size guidance issues in product listings.