# Shopify Admin Customer Cohort Analysis

> Read-only: groups customers by first-purchase month and tracks repeat purchase rate and revenue per cohort.

- **Type:** Skill
- **Install:** `agentstack add skill-40rty-ai-shopify-admin-skills-shopify-admin-customer-cohort-analysis`
- **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-customer-cohort-analysis
- **Website:** http://skills.40rty.ai

## Install

```sh
agentstack add skill-40rty-ai-shopify-admin-skills-shopify-admin-customer-cohort-analysis
```

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

## About

## 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) |
| cohort_months | integer | no | 6 | Number of months of cohorts to analyze |
| follow_months | 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

2. **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

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

## GraphQL Operations

```graphql
# 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
    }
  }
}
```

```graphql
# 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:
```json
{
  "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](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-customer-cohort-analysis
- 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%.