Shopify Admin Refund Rate Analysis

Purpose

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.

Prerequisites

• Authenticated Shopify CLI session: shopify store auth --store --scopes read_orders
• API scopes: read_orders

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | daysback | integer | no | 30 | Lookback window | | groupby | string | no | product | Breakdown: product, vendor, or period | | min_orders | integer | no | 5 | Minimum orders per group to include in rate calculation | | format | string | no | human | Output format: human or json |

Safety

> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

1. OPERATION: orders — query

Inputs: query: "created_at:>=''", first: 250, select refunds { refundLineItems }, lineItems, pagination cursor Expected output: All orders with refund data; paginate until hasNextPage: false

1. For each refunded line item: record product, vendor, quantity refunded, refund amount

1. Aggregate by group_by: calculate refund_rate = refunded_units / total_units_sold × 100

GraphQL Operations

# orders:query — validated against api_version 2025-01
query OrdersWithRefunds($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        lineItems(first: 50) {
          edges {
            node {
              id
              quantity
              product {
                id
                title
                vendor
              }
              variant {
                id
                sku
              }
            }
          }
        }
        refunds {
          id
          createdAt
          totalRefundedSet {
            shopMoney {
              amount
              currencyCode
            }
          }
          refundLineItems(first: 50) {
            edges {
              node {
                quantity
                lineItem {
                  product {
                    id
                    title
                    vendor
                  }
                  variant {
                    id
                    sku
                  }
                }
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Refund Rate Analysis                 ║
║  Store:                        ║
║  Started:              ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL]   
          → Params: 
          → Result: 

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
REFUND RATE ANALYSIS  ( days)
  Orders analyzed:       
  Orders with refunds:   
  Overall refund rate:   %
  Total refunded:        $

  By :
    ""   Sold:   Refunded:   Rate: %
  Output: refund_rate_.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "refund-rate-analysis",
  "store": "",
  "period_days": 30,
  "orders_analyzed": 0,
  "orders_with_refunds": 0,
  "overall_refund_rate_pct": 0,
  "total_refunded": 0,
  "currency": "USD",
  "output_file": "refund_rate_.csv"
}

Output Format

CSV file refund_rate_.csv with columns: group, group_name, total_units_sold, refunded_units, refund_rate_pct, total_refund_amount, currency

Error Handling

| Error | Cause | Recovery | |-------|-------|----------| | THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times | | No refunds in window | Clean period | Exit with 0% rate, expected | | Deleted product on refund line | Product removed after refund | Log as "deleted product" in group |

Best Practices

• A refund rate above 5–10% on specific products typically signals a listing, quality, or expectation mismatch issue.
• Use group_by: vendor to identify if quality problems are concentrated with a specific supplier.
• Cross-reference high-refund products with return-reason-analysis to understand whether the issue is product quality, wrong size, or customer expectation.
• Run before quarterly supplier reviews to support data-driven conversations about product quality and chargebacks.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 40RTY-ai
• Source: 40RTY-ai/shopify-admin-skills
• License: MIT
• Homepage: http://skills.40rty.ai

Install and usage instructions live in the source repository linked above.