Analytics
Two dashboards, one data source. Both compute on demand from Shopify orders. No external warehouse, no daily ETL job, no stale data — just live queries against Shopify with a thin sliding cache for performance.
Admin dashboard (KPI for the merchant)
Open Admin → Analytics. You'll see:
- Order count — total orders in the period.
- Volume — gross sales total (currency from your shop default).
- Commissions total — sum of all earnings in the period.
- Commissions paid — how much you've already paid out.
- Commissions pending — earnings not yet in a payment.
- Top agents — table of agents ranked by volume.
- Top customers — companies ranked by spend.
- Revenue trend — small spark chart of daily volume.
Filters: period (week / month / year / custom), agent, company. Comparison toggle shows the previous equivalent period side-by-side.
Agent dashboard (KPI scoped per agent)
From the agent app, the Commissions tab and home tiles show:
- Personal volume in the current period.
- Commissions earned (paid + pending breakdown).
- Top customers (only the agent's assigned ones).
- Recent orders + drafts list.
Strict scoping: the agent endpoint never returns data outside the agent's assignment / territory.
Period selector and comparison
Periods supported:
- This week — Mon–Sun in the shop's timezone.
- This month — calendar month.
- This year — calendar year.
- Custom range — any start/end dates.
Comparison: when on, the dashboard shows the previous equivalent period. "This week vs last week", "This month vs last month", and so on. Custom ranges compare to the same-length window immediately before.
Caching behavior
Every analytics query goes through a sliding cache in Upstash:
| Range type | TTL | Invalidation |
|---|---|---|
| Live preset (this week / month / year) | 60 seconds | Refund webhook calls bustShop() to invalidate. |
| Custom past range | 5 minutes | Same — refund invalidates everything for the shop. |
This means you don't pay GraphQL cost for repeated dashboard refreshes within the cache window, and a refund hitting your store always invalidates downstream metrics within seconds.
If KV_REST_API_URL isn't configured, caching degrades open — every dashboard query goes straight to Shopify. Functional, but slower. Recommended for production.
Top customers / top agents tables
Both tables are sortable client-side and exportable as CSV via the same export endpoint as commissions. Useful for monthly leaderboard recognition or commercial planning.