/shopify-admin-traffic-by-page-report

name: shopify-admin-traffic-by-page-report
role: conversion-optimization
description: "Report sessions, conversion rate, and bounce rate for every product and collection page using Shopify's analytics API — surfaces which pages earn eyeballs and which convert them."
toolkit: shopify-admin, shopify-admin-execution
api_version: "2025-01"
graphql_operations:
  - shopifyqlQuery:query
status: stable
compatibility: Claude Code, Cursor, Codex, Gemini CLI

Purpose

Queries Shopify's built-in analytics engine (ShopifyQL) to surface session-level traffic data scoped to product and collection pages. Shows which pages are attracting the most traffic, how many sessions convert to orders, and where visitors are bouncing — ready input for SEO prioritisation, merchandising focus, and A/B test targeting. Read-only — no mutations are executed.

Prerequisites

• Authenticated Shopify CLI session: `shopify auth login --store <domain>`
• API scopes: `read_reports`
• Shopify plan: ShopifyQL analytics is available on Basic and above; availability of `sessions` as a data source requires Shopify plan or higher

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | format | string | no | human | Output format: `human` or `json` | | dry_run | bool | no | false | Preview operations without executing mutations | | days_back | integer | no | 30 | Lookback window in days (e.g., `30` = last 30 days) | | page_type | string | no | both | Filter to: `products`, `collections`, or `both` | | top_n | integer | no | 25 | Number of pages to show in the ranked output | | sort_by | string | no | sessions | Ranking metric: `sessions`, `conversion_rate`, or `bounce_rate` |

Workflow Steps

1. **OPERATION:** `shopifyqlQuery` — query (all landing pages) **Inputs:** ShopifyQL string `FROM sessions SHOW sessions, conversion_rate GROUP BY landing_page_path SINCE -<days_back>d UNTIL today ORDER BY sessions DESC LIMIT 250`; `sessions` and `conversion_rate` are the confirmed available metrics for this data source **Expected output:** All landing pages with session counts and conversion rates; paginate via `OFFSET` if result count equals 250

2. **In-memory filtering:** Filter rows where `landing_page_path` starts with `/products/` (product pages) or `/collections/` (collection pages); apply `page_type` parameter; sort by `sort_by`; truncate to `top_n`; flag pages with sessions above median and `conversion_rate < 0.02` as `high_traffic_low_conversion`

> **Note:** ShopifyQL does not support `LIKE`, `WHERE` string prefix filters, or aggregate aliases that shadow reserved column names (`sessions`, `conversion_rate`). All page-type filtering must be done in-memory after fetching all rows.

GraphQL Operations

# shopifyqlQuery:query (page traffic) — validated against api_version 2025-01
query TrafficByPage($query: String!) {
  shopifyqlQuery(query: $query) {
    parseErrors
    tableData {
      columns {
        name
        dataType
        displayName
      }
      rows
    }
  }
}

The `$query` variable (single call — all landing pages, filtered in-memory):

FROM sessions
SHOW sessions, conversion_rate
GROUP BY landing_page_path
SINCE -<days_back>d
UNTIL today
ORDER BY sessions DESC
LIMIT 250

Then filter rows in-memory:

• Product pages: `landing_page_path.startsWith('/products/')`
• Collection pages: `landing_page_path.startsWith('/collections/')`
• `conversion_rate` is returned as a decimal (e.g. `0.016` = 1.6%) — multiply by 100 for display

> **Confirmed live against 2025-01:** `sessions` (INTEGER) and `conversion_rate` (PERCENT) are the available metrics. `WHERE … LIKE`, `bounce_rate`, `converted_sessions`, and aggregate aliases that shadow reserved names are not supported in ShopifyQL `FROM sessions`.

Session Tracking

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

**On start**, emit:

╔══════════════════════════════════════════════╗
║  SKILL: traffic-by-page-report               ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

**After each step**, emit:

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

**On completion**, emit:

For `format: human` (default):

══════════════════════════════════════════════
OUTCOME SUMMARY
  Lookback window:      <days_back> days
  Page type:            <products|collections|both>
  Pages analysed:       <n>
  Top session page:     <path> (<n> sessions)
  Top converting page:  <path> (<pct>%)
  Errors:               0
  Output:               traffic_by_page_<date>.csv
══════════════════════════════════════════════

For `format: json`, emit:

{
  "skill": "traffic-by-page-report",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "ProductPageTraffic", "type": "query", "params_summary": "products, last <days_back> days", "result_summary": "<n> product pages returned", "skipped": false },
    { "step": 2, "operation": "ProductPageTraffic", "type": "query", "params_summary": "collections, last <days_back> days", "result_summary": "<n> collection pages returned", "skipped": false }
  ],
  "outcome": {
    "days_back": 30,
    "page_type": "both",
    "pages_analysed": 0,
    "results": [],
    "errors": 0,
    "output_file": "traffic_by_page_<date>.csv"
  }
}

Output Format

CSV file `traffic_by_page_<YYYY-MM-DD>.csv` with one row per page:

| Column | Description | |--------|-------------| | `page_type` | `product` or `collection` | | `page_path` | URL path (e.g., `/products/red-sneaker`) | | `sessions` | Total sessions landing on this page | | `conversion_rate_pct` | Co