Sign in

Audience by product — how many clients bought a product or category

GET https://{organization}.myguper.com/api/order/report/by-product/{dateStart}/{dateEnd}

Clients who bought a given product in a window — matched by product name pattern or SKU — the audience the QON builder can't express, because it has no item, SKU, category or brand column at all. Answers "who bought luggage over $500 this semester", "buyers of these SKUs", in a single call instead of paging hundreds of thousands of line items and grouping client-side.

Match by productNameLike (a list of patterns, OR between them, case- and accent-insensitive, contains) and/or skuRefId (exact). At least one is required. Narrow by unit price (unitPriceMin/unitPriceMax) and by pieces (minQuantity, net of cancellation).

price is the unit price, net of discount — so unitPriceMin/Max filter the unit directly, not price/quantity. This is what separates a real product from a 1-cent promo gift in the same family. value is SUM(price × net quantity) — money spent on the matching items, in cents.

Per row: pieces (net quantity bought), value, lastDate, and matchedPatterns — which of your productNameLike patterns the client hit, so you can show why each one is in the audience. The window and lastDate are in the org timezone. Rows are paginated (e/p); total is the full audience size.

This is the order side only — client id + metrics. Name, email, phone, last store and store group live in register; so do the "exclude these lists" and "must have contact" filters. Enrich and filter with the register operations, and close the loop with register.audience-list.person.create (which takes the client ids).

Name matching inherits the POS naming mess. category/categoryRefId come in empty or inconsistent on some orgs (Cloe included), so name is the reliable key today — but it carries legacy spellings and external-ref patterns. Widen productNameLike when in doubt, and read matchedPatterns to see what actually caught.

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 window (YYYY-MM-DD), inclusive. Cut from order_date in the org timezone.
dateEnd * string End of the window (YYYY-MM-DD), inclusive.

Query parameters

Name Type Description
productNameLike[] array Product name patterns (contains, OR between them, case- and accent-insensitive). Pass one per value: productNameLike[]=a&productNameLike[]=b. Required unless skuRefId is given.
skuRefId[] array External SKU refs, exact match (OR). Pass one per value. Required unless productNameLike is given.
unitPriceMin integer Minimum unit price in cents (inclusive), on the discounted unit price (`price`). Use it to exclude promo gifts.
unitPriceMax integer Maximum unit price in cents (inclusive).
minQuantity integer Minimum pieces bought, net of cancellation. Default 1.
status string Order status counted. Default `completed`. `all` = everything except canceled.
e integer Entries per page (1-1000). Default 100.
p integer Page number.

Responses

{
  "meta": {
    "unit": "cents", "timezone": "America/Mexico_City",
    "filters": {
      "productNameLike": ["EQUIPAJE VERTICAL","EQUIPAJE VIAJE","SET DE VIAJE","MALETA"],
      "skuRefId": [], "unitPriceMin": 50000, "unitPriceMax": null,
      "minQuantity": 1, "status": "completed"
    }
  },
  "rows": [
    { "client": 4134488, "pieces": 5, "value": 958795715, "lastDate": "2026-06-01",
      "matchedPatterns": ["EQUIPAJE VERTICAL","EQUIPAJE VIAJE","SET DE VIAJE"] }
  ],
  "total": 4624,
  "pagination": { "entries": 100, "currentPage": 1, "totalPages": 47, "isInitial": true, "isEnd": false }
}

Related

Copied to clipboard