Reporting — Customers (GraphQL)

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.

Query	statsAdminReportingCustomers
Endpoint	POST /api/admin/graphql
Returns	A single object: { 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 queries, one per panel, and each is selected with the type argument. 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 statsAdminReportingCustomers 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.

Arguments

Argument	Type	Required	Description
type	String	No	One of the six values above. Defaults to total-customers. An unknown value returns a GraphQL errors[] entry (400, invalid-type).
start	String (YYYY-MM-DD)	No	Lower bound of the reporting window. Defaults to 30 days ago.
end	String (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.

Selection set

query AdminReportingCustomers($type: String, $start: String, $end: String, $channel: String) {
  statsAdminReportingCustomers(type: $type, start: $start, end: $end, channel: $channel) {
    entity
    type
    dateRange
    statistics
  }
}

• entity — always "customers" for this report.
• type — echoes back the requested panel.
• dateRange — a JSON object { previous, current }, each a human-readable label for the corresponding window. This resolves correctly over GraphQL for the reporting queries.
• statistics — a JSON scalar whose shape depends on type (documented below). Query it bare — it has no sub-fields to select.

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

viewStatsAdminReportingCustomers is the detailed table form of the matching statsAdminReportingCustomers query — its statistics carries columns ({ key, label }) and records (the row data behind a panel's View Details link), rather than the rolled-up headline figures. It honors the same type argument.

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.

The CSV Export is REST only (a binary text/csv download); there is no GraphQL equivalent — see the REST endpoint.

Errors

Condition	Result
Missing / invalid Bearer token	401 Unauthenticated
Unknown type value	GraphQL errors[] — "Invalid reporting stat type." (400)

See also

• Reporting — Customers (REST) — same data; also serves the CSV Export.
• Reporting — the sales, customers and products report endpoints.