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 <domain> --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:>='<NOW - cohort_months months>'", first: 250, select id, createdAt, numberOfOrders, pagination cursor Expected output: Customers acquired in the cohort window

2. OPERATION: orders — query Inputs: query: "created_at:>='<NOW - cohort_months + follow_months months>'", 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

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