Shopify Admin Draft Order Cleanup

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

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

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.