Shopify Admin Discount Hygiene Cleanup

Safety

⚠️ discountCodeDelete permanently removes discount codes. Deleted codes cannot be recovered. Customers who received a deleted code will find it invalid. Run with dry_run: true to review the flagged list before committing. Always check that expired codes are not referenced in active email campaigns before deleting.

Workflow Steps

1. OPERATION: discountNodes — query Inputs: first: 250, select discount { ... on DiscountCodeBasic { codes, usageLimit, asyncUsageCount, endsAt, status } }, pagination cursor Expected output: All discount codes with usage and expiry data; paginate until hasNextPage: false

2. Flag discounts matching: flag_expired (status = EXPIRED) and/or flag_zero_usage (asyncUsageCount == 0 AND created > zero_usage_min_age_days ago)

3. OPERATION: discountCodeDelete — mutation Inputs: id: <discount_node_id> Expected output: deletedCodeDiscountId, userErrors

GraphQL Operations

# discountNodes:query — validated against api_version 2025-01
query DiscountAudit($after: String) {
  discountNodes(first: 250, after: $after) {
    edges {
      node {
        id
        discount {
          ... on DiscountCodeBasic {
            title
            status
            createdAt
            endsAt
            asyncUsageCount
            usageLimit
            codes(first: 5) {
              edges {
                node {
                  id
                  code
                }
              }
            }
          }
          ... on DiscountCodeBxgy {
            title
            status
            createdAt
            endsAt
            asyncUsageCount
            usageLimit
          }
          ... on DiscountCodeFreeShipping {
            title
            status
            createdAt
            endsAt
            asyncUsageCount
            usageLimit
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# discountCodeDelete:mutation — validated against api_version 2025-01
mutation DiscountCodeDelete($id: ID!) {
  discountCodeDelete(id: $id) {
    deletedCodeDiscountId
    userErrors {
      field
      message
    }
  }
}

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Discount Hygiene 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
  Discounts scanned:     <n>
  Expired:               <n>
  Zero usage (> <n> days): <n>
  Total flagged:         <n>
  Deleted:               <n>
  Errors:                <n>
  Output:                discount_cleanup_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "discount-hygiene-cleanup",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "dry_run": true,
  "outcome": {
    "scanned": 0,
    "flagged_expired": 0,
    "flagged_zero_usage": 0,
    "deleted": 0,
    "errors": 0,
    "output_file": "discount_cleanup_<date>.csv"
  }
}

Output Format

CSV file discount_cleanup_<YYYY-MM-DD>.csv with columns: discount_id, title, status, created_at, ends_at, usage_count, usage_limit, flag_reason, action

Error Handling

Best Practices

• Run quarterly — discount code sprawl accumulates quickly with seasonal campaigns.
• Check with your email marketing team before deleting zero-usage codes — they may be in a scheduled campaign that hasn't launched yet.
• Keep flag_zero_usage age at 30+ days to avoid deleting codes from recently launched campaigns.
• Automatic/percentage discounts (not code-based) are not cleaned up by this skill — those are managed separately.