Reporting — Overview
| Endpoint | GET /api/admin/reporting/stats |
| Returns | A JSON array with a single element: [ { entity, type, dateRange, statistics } ] |
All admin endpoints require an admin Bearer token — see Authentication.
The Overview endpoint returns a single headline figure across the whole store for the chosen type. It is an API convenience aggregation — there is no matching "Overview" screen in the admin panel (the admin Reporting menu goes straight to Sales / Customers / Products). Use it to fetch one top-line number without having to call the per-section endpoints.
Understanding type — Overview is four separate headlines
A single call returns one headline. The type argument picks which:
total-sales(default) — total revenue for the period.total-orders— number of orders placed.total-customers— number of new customers registered.top-selling-products-by-revenue— the best-selling products by revenue.
The statistics payload changes shape per type — for the three comparison headlines it is an object with a previous-vs-current figure plus an over_time series; for top-selling-products-by-revenue it is a flat array of product rows. Always branch on type when consuming it.
total-sales is the default — if you omit ?type=, you get the total-revenue headline.
Query parameters
| Param | Type | Required | Description |
|---|---|---|---|
type | enum | No | One of the four values above. Defaults to total-sales. |
start | date (YYYY-MM-DD) | No | Lower bound of the reporting window. Defaults to 30 days ago. |
end | date (YYYY-MM-DD) | No | Upper bound. Defaults to today. |
channel | string | No | Channel code (e.g. default) to scope the figures to a single storefront channel. Defaults to all channels. |
start / end drive both the figures and the previous baseline used for each progress percentage — the previous period is the same-length window immediately before start.
Response envelope
The endpoint always returns a single-element array: [ { entity, type, dateRange, statistics } ].
entity— always"overview".type— echoes back the requested headline.dateRange— an object{ previous, current }naming the two comparison windows.currentis the window you asked for;previousis the equal-length window immediately before it.statistics— an object or array whose shape depends ontype(documented below).
Figures with a previous / current / progress shape are period comparisons: current is the chosen window, previous is the preceding window of equal length, and progress is the percentage change (can be negative).
No View Details, no Export
Unlike the Sales / Customers / Products pages, the Overview endpoint has no View Details and no Export — it is a top-line summary only. Reporting requires only authentication; there is no permission gate.
Response shapes by type
total-sales
| Key | Shape | Meaning |
|---|---|---|
sales | { previous, current, formatted_total, progress } | Gross sales in the window; formatted_total is the current value in base currency. |
over_time | { previous, current } — each an array of { label, total, count } | One bucket per day for the chart line, given for both the previous and current windows. total is sales, count is order count. |
total-orders
| Key | Shape | Meaning |
|---|---|---|
orders | { previous, current, progress } | Orders placed in the window. |
over_time | { previous, current } — each an array of { label, total, count } | One bucket per day for both windows. total is the order count for the day; count mirrors it. |
total-customers
| Key | Shape | Meaning |
|---|---|---|
customers | { previous, current, progress } | New customers registered in the window. |
over_time | { previous, current } — each an array of { label, total } | One bucket per day for both windows. |
over_time rows differ for customers
For total-customers, the over_time rows carry only label and total — there is no count field (unlike total-sales / total-orders).
top-selling-products-by-revenue
statistics is a flat array (up to ~5 rows) — there is no previous-vs-current wrapper. Each row: id, name, price, formatted_price, revenue, formatted_revenue, images (array of { id, type, path, product_id, position, url }), and progress (the row's change vs. the previous window, can be negative).
Errors
| Condition | HTTP | Body |
|---|---|---|
| Missing / invalid Bearer token | 401 | { "message": "Unauthenticated.", "error": "unauthenticated" } |
See also
- Reporting — Overview (GraphQL) — same data over the
statsAdminReportingOverviewquery. - Dashboard Statistics — the headline cards behind the admin Dashboard screen.