Shopify Admin Customer Cohort Analysis

Purpose

Groups customers by the month of their first purchase and tracks how each cohort performs over time: how many customers repurchase, how many orders they place, and how much revenue each cohort generates in subsequent months. Cohort analysis is the gold standard for measuring retention and the health of a subscription or loyalty program. Read-only — no mutations.

Prerequisites

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

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | cohortmonths | integer | no | 6 | Number of months of cohorts to analyze | | followmonths | integer | no | 3 | Number of months to follow each cohort after acquisition | | format | string | no | human | Output format: human or json |

Safety

> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

1. OPERATION: customers — query

Inputs: query: "created_at:>=''", first: 250, select id, createdAt, numberOfOrders, pagination cursor Expected output: Customers acquired in the cohort window

1. OPERATION: orders — query

Inputs: query: "created_at:>=''", first: 250, select customer { id }, createdAt, totalPriceSet, pagination cursor Expected output: All orders to build per-customer purchase timeline

1. Group customers by first-order month (cohort); for each cohort, calculate repeat purchase rate and total revenue in months 1, 2, 3+

GraphQL Operations

# customers:query — validated against api_version 2025-01
query CohortCustomers($query: String!, $after: String) {
  customers(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        createdAt
        numberOfOrders
        amountSpent {
          amount
          currencyCode
        }
        defaultEmailAddress {
          emailAddress
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# orders:query — validated against api_version 2025-01
query CohortOrders($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          id
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Customer Cohort Analysis             ║
║  Store:                        ║
║  Started:              ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL]   
          → Params: 
          → Result: 

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
CUSTOMER COHORT ANALYSIS
  Cohort months analyzed:  
  Total customers tracked: 

  Cohort      Acquired  M+1 Repeat  M+2 Repeat  M+3 Repeat
  ──────────────────────────────────────────────────────────
  2026-01            %       %       %
  2026-02            %       %       %
  Output: cohort_analysis_.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "customer-cohort-analysis",
  "store": "",
  "cohorts": [],
  "output_file": "cohort_analysis_.csv"
}

Output Format

CSV file cohort_analysis_.csv with columns: cohort_month, customers_acquired, repeat_purchasers, repeat_rate_pct, total_revenue, revenue_per_customer, month_offset

Error Handling

| Error | Cause | Recovery | |-------|-------|----------| | THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times | | Insufficient history | Store newer than cohort window | Analyze available months only | | Guest checkout orders | No customer record | Exclude from cohort tracking |

Best Practices

• A healthy ecommerce business typically sees 20–40% of first-month customers repeat within 90 days — use this as a benchmark.
• Declining repeat rates in recent cohorts may signal product quality issues, CX friction, or increased competition.
• Use follow_months: 6 for subscription-oriented businesses where the repeat window is longer.
• Pair with customer-spend-tier-tagger — customers from high-repeat cohorts are your best candidates for the Gold/Platinum tier.

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.