Reporting — Customers

Returns the aggregate statistics that power the Bagisto admin Reporting → Customers report — new customers, traffic, top spenders, most orders, most reviews and top customer groups.

Endpoint	GET /api/admin/reporting/customers
Returns	A JSON array with a single element: [ { entity, type, dateRange, statistics } ]

All admin endpoints require an admin Bearer token — see Authentication.

Understanding type — the report is six separate calls

The Customers report screen is not one response. It is assembled from six independent requests, one per panel, and each is selected with the ?type= query parameter. These six groups are exactly the panels of the admin Reporting → Customers screen — no more, no less.

So a single call returns one panel of the report. To render the full screen, call the endpoint once per type (or only for the panels you need). The statistics payload changes shape per type — sometimes an object, sometimes a flat array — so always branch on type when consuming it.

Which type maps to which panel

Report panel (admin)	type	statistics is
Total Customers chart	total-customers	object (with over_time series)
Customers Traffic chart	customers-traffic	object (with over_time series)
Customers With Most Sales list	customers-with-most-sales	array
Customers With Most Orders list	customers-with-most-orders	array
Customers With Most Reviews list	customers-with-most-reviews	array
Top Customer Groups list	top-customer-groups	array

total-customers is the default — if you omit ?type=, you get the "Total Customers" chart.

Query parameters

Param	Type	Required	Description
type	enum	No	One of the six values above. Defaults to total-customers. An unknown value returns 400 (invalid-type).
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 to scope the figures to a single 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 "customers" for this report.
• type — echoes back the requested panel.
• dateRange — an object { previous, current }, where each value is a human-readable label for the corresponding window (e.g. "10 May 2026 - 09 Jun 2026").
• statistics — an object or array whose shape depends on type (documented below).

Response shapes by type

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).

total-customers

Key	Shape	Meaning
customers	{ previous, current, progress }	New customers registered.
over_time	{ previous: [{ label, total }], current: [{ label, total }] }	Two series — previous and current windows — one bucket per day for the chart line.

customers-traffic

Key	Shape	Meaning
total	{ previous, current, progress }	All customer visits.
unique	{ previous, current, progress }	Unique customer visits.
over_time	{ previous: [{ label, total }], current: [{ label, total }] }	Two daily series for the chart.

This panel is chart-only — there is no View Details / Export table for customers-traffic. Traffic figures depend on the Bagisto visitor/analytics tables being populated; on a fresh store the totals are 0 and the over_time series are empty.

customers-with-most-sales

statistics is an array. Each row: id (may be null for guest checkouts), email, full_name, total, orders, progress, formatted_total.

customers-with-most-orders

statistics is an array. Each row: id (may be null for guest checkouts), email, full_name, orders, progress.

customers-with-most-reviews

statistics is an array. Each row: id (may be null for guest reviews), email, full_name, reviews, progress.

top-customer-groups

statistics is an array. Each row: id, group_name, total, progress.

View Details

GET /api/admin/reporting/customers/view returns the same statistics as the summary stats endpoint, but in a detailed table form — the full list that sits behind a panel's View Details link. It honors the same ?type= parameter. The statistics object carries:

• columns — an ordered list of { key, label } describing each table column.
• records — the row data, each keyed by the column key values (records may carry extra fields beyond the displayed columns).

The table columns per type:

type	columns (key)
total-customers	label, total
customers-with-most-sales	full_name, email, formatted_total
customers-with-most-orders	full_name, email, orders
customers-with-most-reviews	full_name, email, reviews
top-customer-groups	group_name, total

customers-traffic is chart-only and has no table form.

Export (CSV)

GET /api/admin/reporting/customers/export streams the same detailed table as a csv, xls or xlsx attachment (the Export button). It honors the same ?type=. The header row is built from the column labels, followed by one line per record. Send the Accept header matching the requested format and save the response to a file.

?format= accepts csv (the default), xls and xlsx — any other value returns HTTP 422. Send an Accept header matching the format: text/csv, application/vnd.ms-excel or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

Both View Details and Export require only authentication; reporting has no permission gate.

Errors

Condition	HTTP	Body
Missing / invalid Bearer token	401	{ "message": "Unauthenticated.", "error": "unauthenticated" }
Unknown type value	400	{ ... "Invalid reporting stat type." }
format other than csv on Export	422	{ ... "Unsupported export format." }

See also

• Reporting — Customers (GraphQL) — same data over the statsAdminReportingCustomers query.
• Reporting — the sales, customers and products report endpoints.