Shopify Admin Customer Win Back

Purpose

Segments lapsed customers — those who placed at least one order but have not purchased again within a configurable window — and tags them for re-engagement. This skill handles the Shopify-native data layer; sending re-engagement emails requires an external tool.

Prerequisites

• Authenticated Shopify CLI session: shopify auth login --store
• API scopes: read_customers, write_customers

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store | string | yes | — | Store domain | | format | string | no | human | human or json | | dryrun | bool | no | false | Preview without tagging | | inactivedays | integer | no | 90 | Days since last order to qualify as lapsed | | minorders | integer | no | 1 | Minimum lifetime order count to include | | tag | string | no | win-back | Tag applied to lapsed customers | | maxcustomers | integer | no | 500 | Maximum customers to process per run |

Workflow Steps

1. OPERATION: customers — query

Inputs: filter last_order_date:=(min_orders), first: 250, pagination Expected output: List of customer objects with id, defaultEmailAddress { emailAddress }, firstName, lastName, ordersCount, lastOrder.processedAt; paginate until hasNextPage: false

1. OPERATION: tagsAdd — mutation

Inputs: Customer id, tag string from tag parameter Expected output: Confirmation per customer; collect userErrors

GraphQL Operations

# customers:query — validated against api_version 2025-04
query LapsedCustomers($first: Int!, $after: String, $query: String) {
  customers(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        defaultEmailAddress {
          emailAddress
        }
        firstName
        lastName
        ordersCount
        lastOrder {
          processedAt
          totalPriceSet {
            shopMoney {
              amount
              currencyCode
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# tagsAdd:mutation — validated against api_version 2025-01
mutation TagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Customer Win-Back                    ║
║  Store:                        ║
║  Started:              ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL]   
          → Params: 
          → Result: 

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

On completion, for format: human:

══════════════════════════════════════════════
OUTCOME SUMMARY
  Lapsed customers found:  
  Customers tagged:        
  Errors:                  
  Output:                  winback_.csv
══════════════════════════════════════════════

For format: json, emit the standard JSON schema with outcome keys: lapsed_found, customers_tagged, errors, output_file.

Output Format

CSV winback_.csv with columns: customer_id, email, first_name, last_name, orders_count, last_order_date, tag_applied

Error Handling

| Error | Cause | Recovery | |-------|-------|----------| | THROTTLED | Rate limit | Wait 2s, retry up to 3 times | | userErrors on tagsAdd | Customer not found or invalid ID | Log, skip, continue |

Best Practices

• Use a dated tag (e.g., win-back-2026-04) so you can track which cohort was targeted each month and avoid re-tagging customers who already received a win-back campaign.
• Set min_orders: 2 to focus on customers who had a genuine purchase relationship, not one-time buyers who may never have intended to return.
• Run with dry_run: true first to validate the lapsed customer count before tagging — the count informs the scale of your re-engagement campaign.

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
• Source: 40RTY-ai/shopify-admin-skills
• License: MIT
• Homepage: http://skills.40rty.ai

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