Metorik Skill

WooCommerce analytics via the Metorik Reporting API. Built for PAI (Personal AI Infrastructure) as a Claude Code skill.

What This Does

A CLI tool + 17 workflow patterns for pulling live revenue, order, product, subscription, customer, coupon, and profit data from any WooCommerce store via Metorik's API. Designed as a pure data access layer that other skills (dashboards, briefings, scheduled agents) can consume.

Capabilities

Base Queries (9 workflows) — Direct API wrappers:

• Revenue by date (time series with grouping)
• Orders by date (AOV, items, customer count)
• Product sales ranking (paginated, sortable)
• Subscription health (MRR, churn, new subs)
• Source attribution (referrer, UTM, landing page)
• Customer acquisition (new customers, grouped-by dimensions)
• Coupon usage and ROI (with profit attribution)
• Profit and COGS breakdown (5 cost categories)
• Setup and validation

Campaign & Comparison Queries (8 workflows) — Business intelligence:

• Multi-year campaign comparison (aligned by campaign day, not calendar date)
• General-purpose revenue comparison (any two periods)
• Geographic revenue by state
• Customer source LTV ranking
• Payment method analysis
• Refund rate monitoring
• Product velocity alerts (week-over-week changes)
• Customer entry product analysis (gateway products)

Setup

1. Get a Metorik API Key

1. Log into Metorik
2. Navigate to Settings > Metorik API
3. Click Create API Key
4. Configure:
   • Name: PAI (or any descriptive name)
   • Scope: Reports & Data (read-only analytics)
   • Expiration: None (or set one if preferred)
5. Copy the key immediately — it is shown only once

2. Store the Key

echo 'YOUR_API_KEY_HERE' > ~/.claude/.metorik-api-key
chmod 600 ~/.claude/.metorik-api-key

3. Validate

bun Tools/MetorikAPI.ts setup

4. Test a Query

bun Tools/MetorikAPI.ts revenue --from 2026-04-01 --to 2026-04-07 --group-by day

CLI Reference

bun Tools/MetorikAPI.ts <command> [options]

Commands

Command	Description
store	Store info (name, timezone, currency)
revenue	Revenue by date (time series)
orders	Orders by date (AOV, items)
customers	Customers by date
profit	Profit with COGS breakdown
subscriptions	MRR, churn, new subs
products	Product sales (paginated)
categories	Category sales
brands	Brand sales
coupons	Coupon usage and ROI
sources	Order sources by referrer
sources-utms	Order sources by UTM params
sources-landing	Order sources by landing page
customer-sources	Customer acquisition with LTV
revenue-grouped	Revenue by dimension
orders-grouped	Orders by dimension
customers-grouped	Customers by dimension
search	Search across resources
custom-metrics	List custom metrics
custom-metric-value	Compute a custom metric
setup	Validate API key and connection

Common Options

Option	Description
--from YYYY-MM-DD	Start date (store timezone)
--to YYYY-MM-DD	End date
--group-by	hour, day, week, month, year
--grouped-by	Dimension for grouped reports
--segment ID	Saved segment ID from Metorik UI
--page N	Page number
--per-page N	Results per page (max 100)
--order-by FIELD	Sort field
--order-dir asc|desc	Sort direction
--search TERM	Filter/search term
--source-type	Comma-separated UTM fields

Examples

# Weekly revenue for March
bun Tools/MetorikAPI.ts revenue --from 2026-03-01 --to 2026-03-31 --group-by week

# Top 25 products by net sales
bun Tools/MetorikAPI.ts products --from 2026-03-01 --to 2026-03-31 \
  --order-by net_sales --order-dir desc --per-page 25

# Revenue by state
bun Tools/MetorikAPI.ts revenue-grouped --from 2026-03-01 --to 2026-03-31 \
  --grouped-by billing_address_state

# Customer sources ranked by LTV
bun Tools/MetorikAPI.ts customer-sources --from 2026-01-01 --to 2026-03-31

# UTM campaign attribution
bun Tools/MetorikAPI.ts sources-utms --from 2026-04-08 --to 2026-04-15 \
  --source-type utm_source,utm_medium,utm_campaign

# Customers grouped by first product purchased (gateway analysis)
bun Tools/MetorikAPI.ts customers-grouped --from 2026-01-01 --to 2026-03-31 \
  --grouped-by first_product

Architecture

This skill is designed as a query layer — it wraps the Metorik API and returns structured JSON. It intentionally contains no business logic or domain-specific interpretation.

Query/Interpretation boundary: If a pattern can run with ONLY Metorik data + a date range, it's a query and lives here. If it requires external domain knowledge or data from other sources (GA4, email marketing, etc.), it's an interpretation and belongs in a consumer skill.

This separation means:

• The CLI tool and workflows are reusable across any WooCommerce store
• Business-specific analysis (seasonality models, retention strategies) stays in your private skills
• Adding new queries requires zero changes to existing ones

API Reference

Full endpoint documentation is in ApiReference.md. Key details:

• Base URL: https://app.metorik.com/api/v1/store
• Auth: Bearer token in Authorization header
• Rate Limit: 30 requests/minute per store (tool handles this with automatic backoff)
• API Status: Beta (response shapes may change)
• OpenAPI Spec: https://metorik.dev/openapi.yaml
• Response caps: 1500 rows/periods max on all report endpoints

File Structure

metorik-skill/
├── README.md
├── SKILL.md                        # PAI skill routing
├── ApiReference.md                 # Full API endpoint docs
├── Tools/
│   └── MetorikAPI.ts               # CLI tool (Bun/TypeScript, 20 commands)
└── Workflows/
    ├── Revenue.md                  # Base queries (9)
    ├── Orders.md
    ├── Products.md
    ├── Subscriptions.md
    ├── Sources.md
    ├── Customers.md
    ├── Coupons.md
    ├── Profit.md
    ├── Setup.md
    ├── CampaignComparison.md       # Campaign & comparison queries (8)
    ├── RevenueComparison.md
    ├── GeographicRevenue.md
    ├── SourceLtvRanking.md
    ├── PaymentMethodAnalysis.md
    ├── RefundMonitor.md
    ├── ProductVelocityAlert.md
    └── CustomerEntryProduct.md

Prerequisites

• Bun runtime
• Metorik account with API access enabled
• A WooCommerce store connected to Metorik

Notes

• All dates use the store's configured timezone (check with bun Tools/MetorikAPI.ts store)
• The --group-by week option returns ISO week numbers (e.g., "2026-10") — prefer day or month for readable output
• Grouped-by endpoints use different field names than time-series endpoints — see workflow files for schema docs
• The tool handles rate limiting automatically (30 req/min with retry on HTTP 429)

---

Written by Verbum, Ben's PAI DA (Digital Assistant), with workflow contributions from Orphu, an OpenClaw agent powered by OpenAI GPT-5.4-Codex. Architecture validated via 12-agent red team analysis. Powered by Claude Opus 4.6.