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

Parameters

Workflow Steps

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

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: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary>
          → Result: <count or outcome>

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

On completion, for format: human:

══════════════════════════════════════════════
OUTCOME SUMMARY
  VIP customers found:  <n>
  Customers tagged:     <n>
  Errors:               <n>
  Output:               loyalty_segment_<date>.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

Best Practices