convez.ai
SkillDados & AnalyticsIntermediário
devkindhq

ShopifyQL Skill para Claude Code

devkindhq/shopifyql-skill

Queries Shopify em inglês simples — Claude faz o resto

Ver no GitHub
BomPluginScore · de 0 a 100

Skill que permite escrever, executar e debugar queries ShopifyQL e Segment Query Language contra sua loja Shopify em linguagem natural. Claude transforma perguntas de negócio em queries otimizadas, executa contra dados live e formata resultados automaticamente.

Instalação

$npx convez-ai devkindhq/shopifyql-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Gerar relatórios de vendas e produtos sem abrir dashboards Shopify
  • Debugar e testar queries ShopifyQL diretamente do editor
  • Criar filtros de segmentação de clientes automaticamente
  • Automatizar relatórios recorrentes em pipelines CI/cron

Veredito

Skill robusto e bem mantido que elimina fricção ao trabalhar com ShopifyQL. Essencial para merchants, analistas e devs Shopify que precisam de queries ágeis sem memorizar sintaxe complexa.

README

A tradução para o português deste README ainda está na fila.

License Version Stars Claude Code Works With

ShopifyQL Skill for Claude Code

The fastest way to query, execute, and debug Shopify analytics — ask a business question in plain English, get live results from your store.

ShopifyQL Skill demo

Ask Claude a business question → ShopifyQL query written → executed against your live Shopify store → results in chat.


Quick Install

/plugin install devkindhq/shopifyql-skill

Works with Claude Code CLI, VS Code extension, JetBrains extension, and Claude.ai web app.


Why Use This Instead of...

ApproachWhat you getWhat you lose
Raw Shopify GraphQL APIFull controlMust know ShopifyQL syntax, zero AI help, no debugging
Shopify Analytics dashboardsVisual UINo automation, no custom queries, no AI interpretation
shopifyql-py (official SDK)Python bindingsNo AI layer, no natural language, no agent execution
This skillAI writes + runs + debugs queries for youNothing

Who It's For

Shopify merchants and analysts — Ask "what were my top 10 products by revenue last quarter?" and get a formatted table without opening the Shopify dashboard or writing a single line of ShopifyQL.

Shopify app developers — Test and iterate ShopifyQL queries against the Admin API directly from your editor. Claude catches syntax errors, handles rate limits, and routes output automatically.

eCommerce agencies — Automate recurring analytics reports and Segment Query Language expressions across client stores. Run queries from CI, cron jobs, or agentic pipelines.


Built by Devkind

This plugin is built and maintained by Devkind — a Melbourne-based agency specialising in Shopify Plus development, Shopify development, and AI platform & integration services.

We build agentic AI systems for eCommerce — automated reporting, cross-channel attribution, and custom AI agents that pull insights from Shopify, Meta, Google Ads, and GA4. Get in touch if you want a custom analytics pipeline for your store.


What It Does

Triggers automatically when you ask Claude to:

  • Write a ShopifyQL report query against your store data
  • Run or execute a query against your live Shopify store
  • Build a Shopify customer segment filter
  • Debug a ShopifyQL syntax error
  • Translate a business question into a Shopify analytics query
  • Understand available ShopifyQL tables, dimensions, or metrics

Also works as a standalone skill for Cursor, GitHub Copilot CLI (Codex), and Gemini CLI — drop skills/shopifyql/SKILL.md into any AI coding tool.


Quick Start

  1. Install the plugin

    /plugin install devkindhq/shopifyql-skill
    
  2. Set your credentials

    export SHOPIFY_STORE_URL=my-store.myshopify.com
    export SHOPIFY_ACCESS_TOKEN=shpat_xxxx
    
  3. Ask Claude a question

    "What were my top 10 products by revenue last quarter?"

  4. Say "run it" to execute the query against your live store.

  5. Get results as a table in chat (≤ 20 rows) or CSV file (> 20 rows).


Execution Setup

Requirements

  • Python 3.11: brew install python@3.11
  • Dependencies: pip3.11 install 'shopifyql[all]' pandas python-dotenv certifi
  • A Shopify Custom App with scopes: read_analytics, read_reports, read_customers, read_orders

Credentials

Credentials must be set as OS environment variables before launching Claude:

export SHOPIFY_STORE_URL=my-store.myshopify.com
export SHOPIFY_ACCESS_TOKEN=shpat_xxxx

Or pass them inline:

SHOPIFY_STORE_URL=my-store.myshopify.com SHOPIFY_ACCESS_TOKEN=shpat_xxxx claude

For guided setup:

/shopifyql-setup

Running the script directly

python3.11 scripts/execute_query.py \
  --query "FROM sales SHOW net_sales SINCE 2026-01-01 UNTIL 2026-01-31"

ShopifyQL Syntax Reference

ShopifyQL is a SQL-like querying language designed specifically for Shopify Plus merchants to analyze store data — including sales, inventory, and customer behavior — without needing advanced coding skills.

It supports powerful features such as time-based filtering, data visualization, and automatic period comparisons. ShopifyQL is accessed via ShopifyQL Notebooks, Shopify Analytics reports, or the GraphQL Admin API.

Clause Order

ClausePurposeExample
FROMData sourceFROM sales
SHOWMetrics to returnSHOW net_sales, orders_count
WHEREFilter by dimensionsWHERE sales_channel = 'online_store'
GROUP BYGroup resultsGROUP BY product_title
HAVINGFilter by metrics (not WHERE)HAVING net_sales > 1000
TIMESERIESData over timeTIMESERIES day
SINCE / UNTILDate rangeSINCE 2026-01-01 UNTIL 2026-01-31
COMPARE TOPeriod comparisonCOMPARE TO previous_year
ORDER BYSort resultsORDER BY net_sales DESC
LIMITLimit rowsLIMIT 20

Powerful ShopifyQL Features

  • DURING — time range shorthand (DURING last_30_days)
  • COMPARE TO — automatic period comparison (COMPARE TO previous_period, previous_year)
  • TIMESERIES — aggregate data over time (TIMESERIES week)
  • VISUALIZE — declare chart type for Shopify Notebooks
  • WITH modifiers — control rounding, currency display, and more
  • Semi-joins — filter using subqueries
  • Math on metrics — (net_sales / orders_count) AS average_order_value
  • TOP N — return top N results per group

Analytics Reports

Build tailored reports within Shopify Analytics — top products, revenue by channel, sales trends over time.

FROM sales
SHOW net_sales, orders_count
GROUP BY sales_channel
SINCE 2026-01-01 UNTIL 2026-03-31
ORDER BY net_sales DESC

Customer Segmentation

Modify and query customer data segments — repeat vs. new buyers, high-value customers, re-engagement targets.

FROM customers
SHOW customer_count
WHERE customer_type = 'returning'
GROUP BY customer_cohort_month
TIMESERIES month

Comparing Sales Periods

Use COMPARE TO for automatic period comparisons — no manual date math needed.

FROM sales
SHOW net_sales, orders_count
SINCE 2026-01-01 UNTIL 2026-03-31
COMPARE TO previous_year

App Development

Leverage the GraphQL Admin API to fetch ShopifyQL data programmatically — for custom dashboards, reporting apps, and agentic pipelines.

Known SDK Quirk

Columns ending in _ms (lcp_p75_ms, inp_p75_ms) trigger a type-cast bug in query_pandas(). Use --raw for these — the executor agent handles this automatically.

# For _ms duration columns (LCP, INP):
python3.11 scripts/execute_query.py --raw \
  --query "FROM web_performance SHOW lcp_p75_ms GROUP BY day TIMESERIES day SINCE 2026-01-01 UNTIL 2026-01-31"

# CSV output:
python3.11 scripts/execute_query.py --output csv \
  --query "FROM sales SHOW net_sales GROUP BY product_title SINCE 2026-01-01 UNTIL 2026-01-31 ORDER BY net_sales DESC LIMIT 20"

Segment Query Language

The skill also covers Shopify Segment Query Language — used to build customer segments with attribute filters, behavioral conditions, and date-based expressions.

Supported features:

  • All attribute types (string, boolean, date, number)
  • All operators (=, !=, >, <, >=, <=, CONTAINS, NOT CONTAINS, IS NULL, IS NOT NULL)
  • Date formats and relative date expressions
  • Functions: products_purchased, orders_placed, shopify_email, anniversary, customer_within_distance, storefront_event
  • Common patterns: re-engagement segments, high-value customers, wholesale/B2B filters

Common ShopifyQL Mistakes (and How to Avoid Them)

1. Double quotes instead of single quotes

ShopifyQL requires single quotes for string values.

-- Wrong
WHERE sales_channel = "online_store"

-- Correct
WHERE sales_channel = 'online_store'

2. Filtering on metrics in WHERE instead of HAVING

WHERE filters dimensions (text/category fields). HAVING filters metrics (numbers).

-- Wrong (net_sales is a metric)
WHERE net_sales > 1000

-- Correct
HAVING net_sales > 1000

3. Missing GROUP BY when showing dimensions

If you SHOW a dimension alongside a metric, you must GROUP BY that dimension.

-- Wrong
FROM sales SHOW net_sales, product_title

-- Correct
FROM sales SHOW net_sales, product_title GROUP BY product_title

4. Rate Limits — 429 errors

ShopifyQL enforces rate limits. If you hit a 429 Too Many Requests error, you must wait 60 seconds before retrying. The executor agent handles this automatically with a backoff retry.


Common eCommerce Patterns

Top products by revenue

FROM sales
SHOW net_sales, orders_count
GROUP BY product_title
SINCE 2026-01-01 UNTIL 2026-03-31
ORDER BY net_sales DESC
LIMIT 10

Revenue by sales channel

FROM sales
SHOW net_sales, orders_count
GROUP BY sales_channel
SINCE 2026-01-01 UNTIL 2026-03-31
ORDER BY net_sales DESC

Sales trend over time

FROM sales
SHOW net_sales
TIMESERIES week
SINCE 2026-01-01 UNTIL 2026-03-31

New vs returning customers

FROM customers
SHOW customer_count
WHERE customer_type = 'returning'
GROUP BY customer_cohort_month
TIMESERIES month

Period-over-period comparison

FROM sales
SHOW net_sales, orders_count
SINCE 2026-01-01 UNTIL 2026-03-31
COMPARE TO previous_year

Use with Cursor, Codex CLI, or Gemini CLI

The ShopifyQL skill is a universal Markdown instruction file that works in any AI coding tool that supports skill/context injection.

To add it manually:

cp skills/shopifyql/SKILL.md .cursor/rules/shopifyql.md  # Cursor
cp skills/shopifyql/SKILL.md .github/copilot-instructions.md  # GitHub Copilot

Note: The live execution layer (Python script + executor agent) is Claude Code-specific. The ShopifyQL knowledge and syntax guidance works in any AI coding tool.


Star History

Star History Chart


Contributing

PRs and issues are welcome. See CONTRIBUTING.md for guidelines.

Found a useful ShopifyQL query? Share it with the community.


Built by Devkind

This plugin was built and is maintained by Devkind — a Melbourne-based development and AI agency specialising in Shopify, custom web applications, and agentic AI systems.

Agentic reporting for Shopify

Devkind builds agentic reporting pipelines that go beyond standard Shopify Analytics dashboards. Instead of switching between tabs and manually interpreting numbers, an AI agent does the analytical heavy lifting — pulling data from Shopify, ad platforms, and Google Analytics, then surfacing what changed, why, and what to do next.

This ShopifyQL plugin is one piece of that stack. If you want:

  • Automated daily Shopify analytics reports delivered to Slack or email
  • Cross-channel attribution (Shopify + Meta + Google Ads unified)
  • A custom AI analytics agent for your ecommerce store
  • ShopifyQL dashboards and Segment Query Language automation

...Devkind can scope and build it for you.

Get in touch


Further Reading


License

MIT

Ver o original no GitHub

Bom para

Relacionados