Sign in

Top products sold

GET https://{organization}.myguper.com/api/order/report/products/{dateStart}/{dateEnd}

The answer to "what sold most", "top products by revenue", "units per SKU", in a single call — instead of paging line items and grouping client-side. Ranks sold items (order_item) by product, SKU, category or brand, in the same scope as the sales report (org, window in the org timezone, store, status).

Per row: units (quantity sold), unitsCanceled, revenue, orders (how many orders included it) and lines. Rows are the top N by revenue (limit, default 50); the total covers every item in the period, not just the top.

Break it down by store or time in one call. groupBy takes a comma list: the first token is the item dimension (product/sku/category/brand) and you may add store and/or one time grain (day/week/month) — e.g. groupBy=product,store, sku,week, product,store,month. With a breakdown the limit picks the top items for the whole period and each row is one cell (item × store × period), so you get the per-store or weekly split without one call per store. Each row then carries storeId, day (YYYY-MM-DD), week (YYYY-Www, ISO) or month (YYYY-MM) as applicable; a cell with no sales is not emitted.

revenue is line revenue — SUM(price × quantity), where price is the item's unit price net of the item discount. It is not the order total, and does not match the sales report's revenue: order-level discounts and adjustments are not pushed down to the item price, so the sum of the lines runs higher (≈+20% measured). Use this for product ranking; use order.report.sales for revenue/billing. Values are in cents.

category and brand come from partial ingestion and are sparse today (single-digit % on some orgs). The endpoint is ready for them now and fills in as ingestion improves — read meta.coverage (the fraction of items and revenue that carry a category/brand) so a breakdown covering 5% of the period is not mistaken for the whole. Rows with a null id are the items missing that field. order_item stores no category/brand name, only the id and external refId.

Try-it values populated from environment ACME (Demo)


Authentication

Token

Send your user token in the x-guper-authorization header.

Headers

Name Type Description
x-guper-authorization * string User token issued by Guper.
Content-Type * string Always `application/json` for endpoints that accept a JSON body.

Path parameters

Name Type Description
dateStart * string Start of the period (YYYY-MM-DD), inclusive. The day is cut from order_date in the org timezone.
dateEnd * string End of the period (YYYY-MM-DD), inclusive.

Query parameters

Name Type Description
groupBy string Comma list: 1st token = item dimension (`product`/`sku`/`category`/`brand`, default `product`); optional extra tokens break it down by `store` and/or one time grain (`day`/`week`/`month`). E.g. `product,store`, `sku,week`, `product,store,month`. `product`/`sku` work today; `category`/`brand` are sparse (see `meta.coverage`). At most one time grain per call.
store integer Restrict to a single store id.
status string Order status. Default: all except canceled.
limit integer How many top rows by revenue (1-500). Default 50. The `total` always covers everything.

Responses

{
  "meta": {
    "unit": "cents", "timezone": "Etc/GMT+6",
    "groupBy": "product", "breakdown": [], "limit": 50,
    "filters": { "store": null, "status": "all except canceled (default)" },
    "coverage": {
      "category": { "items": 0.049, "revenue": 0.065 },
      "brand":    { "items": 0.049, "revenue": 0.061 }
    }
  },
  "rows": [
    { "productId": 0, "productName": "I-2 BILLETERA CLOE P25 564 ROSA /FLAP GR",
      "units": 256, "unitsCanceled": 0, "revenue": 122482432, "orders": 115, "lines": 121 }
  ],
  "total": { "units": 60663, "unitsCanceled": 0, "revenue": 6124205576, "orders": 24815, "lines": 56403 }
}

Related

Copied to clipboard