shopify-admin-order-risk-report

name	shopify-admin-order-risk-report
role	order-intelligence
description	Read-only: lists orders by fraud risk level with indicator details for building a manual review queue.
toolkit	shopify-admin, shopify-admin-execution
api_version	2025-01
graphql_operations	["orders:query"]
status	stable
compatibility	Claude Code, Cursor, Codex, Gemini CLI

Purpose

Queries recent orders and surfaces those with high or medium fraud risk scores, including the specific risk indicators flagged by Shopify (billing/shipping address mismatch, risky email domain, high-risk IP, etc.). Produces a prioritized review queue for manual fraud assessment. Read-only — no mutations.

Prerequisites

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

Parameters

Parameter	Type	Required	Default	Description
store	string	yes	—	Store domain (e.g., mystore.myshopify.com)
risk_level	string	no	high	Minimum risk level to include: high, medium, or all
days_back	integer	no	7	Lookback window for orders to review
min_order_value	float	no	0	Only include orders above this value (USD)
format	string	no	human	Output format: human or json

Safety

ℹ️ Read-only skill — no mutations are executed. Safe to run at any time. Risk scores are generated by Shopify's fraud analysis and are advisory only — they do not block orders automatically unless you configure Shopify's fraud filters.

Workflow Steps

1. OPERATION: orders — query Inputs: query: "risk_level:<risk_level> created_at:>='<NOW - days_back days>'", first: 250, select riskLevel, riskFacts, totalPriceSet, customer, pagination cursor Expected output: Orders with risk data; paginate until hasNextPage: false

2. Sort by risk level (high first), then by order value descending

GraphQL Operations

# orders:query — validated against api_version 2025-01
query OrderRiskReport($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        displayFulfillmentStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        riskLevel
        riskFacts {
          message
          sentiment
        }
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
          numberOfOrders
        }
        shippingAddress {
          countryCode
          city
        }
        billingAddress {
          countryCode
          city
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Order Risk Report                    ║
║  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):

══════════════════════════════════════════════
ORDER RISK REPORT  (<days_back> days)
  Orders reviewed:  <n>
  High risk:        <n>
  Medium risk:      <n>
  Low risk:         <n>

  High Risk Orders:
    #<name>  $<amount>  <customer>
      Risks: <indicator>, <indicator>
  Output: risk_report_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "order-risk-report",
  "store": "<domain>",
  "period_days": 7,
  "orders_reviewed": 0,
  "high_risk_count": 0,
  "medium_risk_count": 0,
  "output_file": "risk_report_<date>.csv"
}

Output Format

CSV file risk_report_<YYYY-MM-DD>.csv with columns: order_name, order_id, created_at, risk_level, total_price, currency, customer_name, customer_email, risk_indicators, financial_status, fulfillment_status

Error Handling

Error	Cause	Recovery
THROTTLED	API rate limit exceeded	Wait 2 seconds, retry up to 3 times
No high-risk orders	Clean period	Exit with summary: 0 flagged orders
riskLevel null	Order too new for analysis	Exclude from report, note count

Best Practices

• Do not auto-cancel high-risk orders — use high-risk-order-tagger to flag them for manual hold first, then review before cancelling.
• An order from a repeat customer (numberOfOrders > 3) with a high risk score is usually a false positive — apply judgment before acting.
• min_order_value helps focus review effort on high-value fraud risk; $50+ is a reasonable floor for most stores.
• Run daily as part of a morning ops routine, especially during high-volume sale periods when fraud attempts increase.