# Shopify Admin Chargeback Watchlist Tagger

> Identifies customers with disputed or charged-back orders and tags their customer record for proactive review on future orders.

- **Type:** Skill
- **Install:** `agentstack add skill-40rty-ai-shopify-admin-skills-shopify-admin-chargeback-watchlist-tagger`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [40RTY-ai](https://agentstack.voostack.com/s/40rty-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [40RTY-ai](https://github.com/40RTY-ai)
- **Source:** https://github.com/40RTY-ai/shopify-admin-skills/tree/main/skills/customer-ops/shopify-admin-chargeback-watchlist-tagger
- **Website:** http://skills.40rty.ai

## Install

```sh
agentstack add skill-40rty-ai-shopify-admin-skills-shopify-admin-chargeback-watchlist-tagger
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Purpose
Scans historical orders for any associated chargeback or dispute, then tags the customer record with `chargeback-history` (configurable). Future orders from these customers can be filtered or held for manual review by ops. Reduces repeated chargeback losses without blocking customers outright. Defaults to `dry_run: true`.

## Prerequisites
- Authenticated Shopify CLI session: `shopify store auth --store  --scopes read_orders,read_customers,write_customers`
- API scopes: `read_orders`, `read_customers`, `write_customers`

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| store | string | yes | — | Store domain (e.g., mystore.myshopify.com) |
| days_back | integer | no | 730 | Historical window to scan for disputes (2 years default) |
| watchlist_tag | string | no | chargeback-history | Tag applied to flagged customers |
| include_won_disputes | bool | no | false | If false, only tag customers whose disputes were lost or are open |
| dry_run | bool | no | true | Preview without applying tags |
| format | string | no | human | Output format: `human` or `json` |

## Safety

> ⚠️ `customerUpdate` modifies customer tags that are visible to staff and may drive segmentation rules. Tag a customer incorrectly and you may downgrade their experience or block their orders. Run with `dry_run: true` first and review the list before committing. Won disputes (where the merchant won) are excluded by default to avoid false positives.

## Workflow Steps

1. **OPERATION:** `orders` — query
   **Inputs:** `query: "created_at:>='' chargeback_status:*"` (any chargeback state), `first: 250`, select `disputes { id, status, initiatedAs, finalizedOn }`, `customer { id, displayName, tags, defaultEmailAddress { emailAddress } }`, `totalPriceSet`, pagination cursor
   **Expected output:** All orders that have at least one dispute in the window

2. Group disputes by customer. For each customer:
   - Skip if every dispute has status `WON` and `include_won_disputes: false`
   - Skip if customer already carries `watchlist_tag`
   - Otherwise add to tagging queue

3. **OPERATION:** `customerUpdate` — mutation
   **Inputs:** `input: { id, tags: [, watchlist_tag] }` for each queued customer
   **Expected output:** Updated customer with new tag list; `userErrors`

4. If `dry_run: true`, do not call mutation — just report the queue.

## GraphQL Operations

```graphql
# orders:query — validated against api_version 2025-01
query OrdersWithDisputes($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        disputes {
          id
          status
          initiatedAs
          finalizedOn
        }
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
          numberOfOrders
          amountSpent {
            amount
            currencyCode
          }
          tags
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

```graphql
# customerUpdate:mutation — validated against api_version 2025-01
mutation TagChargebackCustomer($input: CustomerInput!) {
  customerUpdate(input: $input) {
    customer {
      id
      tags
    }
    userErrors {
      field
      message
    }
  }
}
```

## Session Tracking

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

**On start**, emit:
```
╔══════════════════════════════════════════════╗
║  SKILL: Chargeback Watchlist Tagger          ║
║  Store:                        ║
║  Started:              ║
╚══════════════════════════════════════════════╝
```

**After each step**, emit:
```
[N/TOTAL]   
          → Params: 
          → Result: 
```

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

**On completion**, emit:

For `format: human` (default):
```
══════════════════════════════════════════════
CHARGEBACK WATCHLIST  ( days)
  Orders with disputes:    
  Unique customers:        
  Disputes lost/open:      
  Disputes won (excluded): 
  Already tagged:          
  ─────────────────────────────
  Customers to tag:        
  Tags applied:               (or [DRY RUN] would apply)
  Errors:                  
  Output: chargeback_watchlist_.csv
══════════════════════════════════════════════
```

For `format: json`, emit:
```json
{
  "skill": "chargeback-watchlist-tagger",
  "store": "",
  "dry_run": true,
  "orders_with_disputes": 0,
  "unique_customers": 0,
  "customers_to_tag": 0,
  "tags_applied": 0,
  "errors": 0,
  "output_file": "chargeback_watchlist_.csv"
}
```

## Output Format
CSV file `chargeback_watchlist_.csv` with columns:
`customer_id`, `email`, `name`, `dispute_count`, `latest_dispute_status`, `latest_dispute_initiated_as`, `total_disputed_amount`, `currency`, `existing_tags`, `tag_to_apply`, `action`

## Error Handling
| Error | Cause | Recovery |
|-------|-------|----------|
| `THROTTLED` | API rate limit exceeded | Wait 2 seconds, retry up to 3 times |
| `userErrors` on customerUpdate | Customer not found / archived | Log error, skip, continue |
| Order without a customer | Guest checkout dispute | Cannot tag — record in CSV with `action: skipped_guest` |
| Dispute with status `null` | Very recent dispute, not yet categorized | Treat as open / not won |

## Best Practices
- Always start with `dry_run: true` and audit the CSV — false positives damage customer trust.
- Combine `watchlist_tag` with a Shopify Flow or order-routing rule that holds new orders from tagged customers for manual approval.
- Re-run quarterly so the watchlist stays current — chargeback patterns change as your store and customer base grow.
- Keep `include_won_disputes: false` (default). If you won, the bank ruled in your favor — do not penalize the customer.
- For repeat offenders (multiple disputes), consider escalating beyond a tag — review manually before allowing further orders.

## 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](https://github.com/40RTY-ai)
- **Source:** [40RTY-ai/shopify-admin-skills](https://github.com/40RTY-ai/shopify-admin-skills)
- **License:** MIT
- **Homepage:** http://skills.40rty.ai

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-40rty-ai-shopify-admin-skills-shopify-admin-chargeback-watchlist-tagger
- Seller: https://agentstack.voostack.com/s/40rty-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.