Shopify Admin Partial Refund Pattern Detector

Purpose

Scans recent orders, extracts every refund, and flags orders that have either (a) two or more partial refunds, or (b) a partial-refund-to-order-total ratio above a configurable threshold. These patterns frequently indicate friendly fraud (incremental claims), an unhappy repeat customer pattern, or a staff workflow gap (refunding piecemeal instead of issuing one full credit). 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 | 90 | Lookback window for orders to analyze | | minpartials | integer | no | 2 | Minimum number of partial refunds to flag an order | | ratiothreshold | float | no | 0.5 | Flag orders where total refunded / order total exceeds this ratio (still partial, i.e. below 1.0) | | minorder_value | float | no | 25 | Skip low-value orders below this amount | | format | string | no | human | Output format: human or json |

Safety

> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time. Flagged orders are advisory — confirm with refund notes and customer history before taking action against a customer account.

Workflow Steps

1. OPERATION: orders — query

Inputs: query: "created_at:>='' financial_status:partially_refunded", first: 250, select refunds { id, createdAt, totalRefundedSet, note }, totalPriceSet, customer, pagination cursor Expected output: All partially refunded orders with full refund history; paginate until hasNextPage: false

1. For each order, count refunds and sum totalRefundedSet.shopMoney.amount. Compute ratio = total_refunded / order_total.

1. Flag orders meeting either condition: refund_count >= min_partials OR ratio >= ratio_threshold (and `ratio ║

║ Started: ║ ╚══════════════════════════════════════════════╝

**After each step**, emit:

[N/TOTAL] → Params: → Result:

**On completion**, emit:

For `format: human` (default):

══════════════════════════════════════════════ PARTIAL REFUND PATTERN REPORT ( days) Partially refunded orders: Flagged (multi-refund): Flagged (high ratio): Repeat-flagged customers:

Top flagged customers by amount: Orders: Refunded: $ Ratio: % Output: partialrefundpatterns_.csv ══════════════════════════════════════════════

For `format: json`, emit:
```json
{
  "skill": "partial-refund-pattern-detector",
  "store": "",
  "period_days": 90,
  "partially_refunded_orders": 0,
  "flagged_multi_refund": 0,
  "flagged_high_ratio": 0,
  "repeat_flagged_customers": 0,
  "output_file": "partial_refund_patterns_.csv"
}

Output Format

CSV file partial_refund_patterns_.csv with columns: order_name, order_id, customer_email, customer_lifetime_orders, order_total, total_refunded, refund_ratio, refund_count, flag_reason, first_refund_at, last_refund_at

Error Handling

| Error | Cause | Recovery | |-------|-------|----------| | THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times | | Order has refund but totalRefundedSet is zero | Refund recorded as $0 (note only, no money moved) | Skip from ratio calc, count refund | | Customer is null (guest order) | No customer attached | Group by email instead of customer ID | | No partially refunded orders | Clean window | Exit with summary: 0 flagged |

Best Practices

• Combine min_partials: 2 and ratio_threshold: 0.5 for the most useful signal — single small partial refunds are usually legitimate.
• Sort by refund_ratio descending: high ratios on high-value orders are the strongest fraud signal.
• A repeat-flagged customer with numberOfOrders > 5 is often a chronic complainer, not a fraudster — review the refund notes before action.
• Use this skill quarterly alongside order-risk-report to detect post-purchase fraud that fraud filters miss at checkout.
• Refund note content frequently reveals the pattern (e.g., "item missing" repeated three times) — read the notes before flagging a customer.

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.