Reports

The preorder reports resource returns the numbers the merchant sees on the Preorders Overview and the Reports > Preorders pages. Each report is a JSON read; reads run against read replicas. There is no CSV export in the API.

Path prefix: /preorders/reports

Report catalog

GET /preorders/reports

Open in the API reference

Returns every available report — name, description, aliases, and URL — generated from the live registry. GET /preorders/reports/help returns the expanded shape with full query schemas.

Reads

Method	Path	Dashboard view
GET	/preorders/reports/summary	Preorders Overview tiles
GET	/preorders/reports/by_date	Overview charts (sales, total impact)
GET	/preorders/reports/products	Reports > Preorders > Products > Revenue
GET	/preorders/reports/fulfillments	Reports > Preorders > Fulfillments
GET	/preorders/reports/engagement	Reports > Preorders > Products > Engagement

The order list itself is GET /preorders/orders.

Filters

Param	Type	On	Notes
from, to	ISO 8601 date	all	Window, inclusive, in the shop’s timezone. Defaults to the last 30 days (engagement: the shop’s lifetime).
range	all_time	summary, by_date, products, fulfillments	The dashboard’s All time instead of a window
shopify_market_id	gid or numeric	engagement	Scope to one Shopify market
group_by	variant / product	products, fulfillments
sort_by, direction	string	products, fulfillments, engagement
page, per_page	integer	products, fulfillments, engagement
shopify_variant_ids[]	gid or numeric	engagement	The dashboard’s Product filter: scopes the totals and the per-variant table

Amounts are strings in the shop’s currency (currency in the response). Shopify ids in responses are gid strings: shopify_product_id, shopify_variant_id, shopify_market_id.

Notes per report

• summary — the Overview tiles, shop-wide: orders, units_sold, revenue (the “Total sales” tile, whole orders), line_item_revenue (preorder line items), average order value, unpaid orders and unpaid_balance (orders that owe money now and the sum they owe, read live from the orders), unfulfilled orders and unique customers. The same numbers as the dashboard tiles and the Home analytics card; the rest are summed from the shop’s daily totals. With range=all_time, window is null and orders, revenue and average_order_value come from the shop’s lifetime totals, as Home’s All time does.
• by_date — the two Overview charts, shop-wide, one row per bucket: orders and revenue (the sales chart, whole orders) and units_sold and line_item_revenue (the total impact chart, preorder line items). The bucket size is the dashboard’s: daily up to 60 days, weekly up to 180, then monthly (interval in the response); buckets are UTC days, as on the charts, and date is the bucket’s first day.
• products — units_sold, orders, revenue (line revenue) and last_order_date per variant or product. Preorder line items only. sort_by is one of those keys or product_title.
• fulfillments — in units: sold = cancelled + fulfilled + outstanding, outstanding = waiting + on_hold + scheduled. Cancelled orders are left out; cancelled is units cancelled from an order that is still open (a split order). Statuses are as of now; the window picks when the units were sold.
• engagement — button impressions, add-to-carts and orders, shop-wide and as a paged per-variant table. window is always set: from/to default to the shop’s lifetime here. Rates use unique shoppers; total_* fields count every event. pixel_active is false when the STOQ web pixel is not set up, so there is nothing to count; turn it on with POST /account/web_pixel/enable.

Example: products by revenue

curl 'https://app.stoqapp.com/api/v2/external/preorders/reports/products?from=2026-05-01&to=2026-05-31&group_by=product' \
  -H "X-Auth-Token: $STOQ_API_KEY"