Shopify Admin Loyalty Segment Export

Purpose

Segments your highest-value customers by order count and total lifetime spend, tags them in Shopify, and exports a list ready for loyalty program enrollment or VIP campaign targeting. This skill handles the data layer; managing rewards points or sending loyalty 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 | | minorders | integer | no | 3 | Minimum lifetime order count | | min_spend | float | no | 200 | Minimum lifetime spend (store currency) | | tag | string | no | loyalty-vip | Tag applied to qualifying customers |

Workflow Steps

1. OPERATION: customers — query

Inputs: filter orders_count:>=(min_orders), total_spent:>=(min_spend), first: 250, pagination Expected output: List with id, defaultEmailAddress { emailAddress }, firstName, lastName, ordersCount, totalSpentV2; paginate until hasNextPage: false

1. OPERATION: tagsAdd — mutation

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

GraphQL Operations

# customers:query — validated against api_version 2025-04
query LoyaltyCustomers($first: Int!, $after: String, $query: String) {
  customers(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        defaultEmailAddress {
          emailAddress
        }
        firstName
        lastName
        ordersCount
        totalSpentV2 {
          amount
          currencyCode
        }
        tags
      }
    }
    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: Loyalty Segment Export               ║
║  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
  VIP customers found:  
  Customers tagged:     
  Errors:               
  Output:               loyalty_segment_.csv
══════════════════════════════════════════════

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

Output Format

CSV loyalty_segment_.csv with columns: customer_id, email, first_name, last_name, orders_count, total_spent, currency, tag_applied

Error Handling

| Error | Cause | Recovery | |-------|-------|----------| | THROTTLED | Rate limit | Wait 2s, retry up to 3 times | | userErrors on tagsAdd | Invalid customer ID | Log, skip, continue |

Best Practices

• Before running, check if customers already have the loyalty tag — add NOT tag:loyalty-vip to your query filter to skip already-enrolled customers.
• Export and review the customer list before tagging if you're unsure about the threshold values — use dry_run: true to see the count, then adjust min_orders and min_spend before committing.
• Combine with customer-win-back: tag high-LTV lapsed customers with both loyalty-vip and a win-back tag to identify your highest-priority re-engagement targets.

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.