shopify-admin-draft-order-cleanup

name	shopify-admin-draft-order-cleanup
role	store-management
description	Finds stale draft orders older than N days and optionally deletes them to reduce admin clutter.
toolkit	shopify-admin, shopify-admin-execution
api_version	2025-01
graphql_operations	["draftOrders:query","draftOrderDelete:mutation"]
status	stable
compatibility	Claude Code, Cursor, Codex, Gemini CLI

Purpose

Queries open draft orders older than a configurable age and optionally deletes them. Draft orders accumulate from abandoned B2B quotes, incomplete manual orders, or old integrations and clutter the admin. Stale drafts also inflate pending revenue metrics.

Prerequisites

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

Parameters

Parameter	Type	Required	Default	Description
store	string	yes	—	Store domain (e.g., mystore.myshopify.com)
older_than_days	integer	no	30	Delete drafts older than this many days
dry_run	bool	no	true	Preview drafts to delete without executing mutation
format	string	no	human	Output format: human or json

Safety

⚠️ draftOrderDelete permanently deletes draft orders. Deleted drafts cannot be recovered. Run with dry_run: true to review the list before committing. Check that no stale drafts represent active B2B quotes awaiting customer approval before deleting.

Workflow Steps

1. OPERATION: draftOrders — query Inputs: query: "status:open created_at:<='<NOW - older_than_days days>'", first: 250, pagination cursor Expected output: Stale open draft orders; paginate until hasNextPage: false

2. OPERATION: draftOrderDelete — mutation Inputs: id: <draft_order_id> Expected output: deletedId, userErrors

GraphQL Operations

# draftOrders:query — validated against api_version 2025-01
query StaleDraftOrders($query: String!, $after: String) {
  draftOrders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        status
        createdAt
        updatedAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
        }
        tags
        note
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# draftOrderDelete:mutation — validated against api_version 2025-01
mutation DraftOrderDelete($input: DraftOrderDeleteInput!) {
  draftOrderDelete(input: $input) {
    deletedId
    userErrors {
      field
      message
    }
  }
}

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Draft Order Cleanup                  ║
║  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>

If dry_run: true, prefix every mutation step with [DRY RUN] and do not execute it.

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
OUTCOME SUMMARY
  Stale drafts found:   <n>
  Drafts deleted:       <n>
  Total value cleared:  $<amount>
  Errors:               <n>
  Output:               draft_cleanup_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "draft-order-cleanup",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "older_than_days": 30,
  "dry_run": true,
  "outcome": {
    "drafts_found": 0,
    "drafts_deleted": 0,
    "value_cleared": 0,
    "currency": "USD",
    "errors": 0,
    "output_file": "draft_cleanup_<date>.csv"
  }
}

Output Format

CSV file draft_cleanup_<YYYY-MM-DD>.csv with columns: draft_id, draft_name, customer_name, customer_email, created_at, total_value, currency, action

Error Handling

Error	Cause	Recovery
THROTTLED	API rate limit exceeded	Wait 2 seconds, retry up to 3 times
userErrors on delete	Draft already completed or cancelled	Log as skipped, continue
No stale drafts	All drafts are recent or none exist	Exit with 0 results

Best Practices

• Set older_than_days: 60 or higher for B2B stores where quotes may have longer sales cycles.
• Review the dry-run list for drafts with notes or high value before deleting — these may be legitimate pending quotes.
• For B2B scenarios, consider filtering out drafts tagged with b2b-quote or similar before running the delete step.
• Run monthly as a routine admin hygiene task.