Sign in

Audience by purchase frequency

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

Clients who bought N times in a window, with an optional value floor per purchase — the audience the QON builder can't express, because its RFM is lifetime (no window) and has no notion of a purchase day. Answers "who bought 3+ times over $X this semester", "high-value repeat buyers", "spent more than $Y since January", in a single call instead of paging orders and aggregating client-side.

An occurrence is an order (groupBy=order) or a purchase day (groupBy=purchase_day), where the tickets of the same day are summed — retail splits one purchase across several tickets, so the day, not the order, is the unit the campaign means. On Cloe's 2026 this is 14% of the audience.

valueMode sets the floor: all = every occurrence ≥ valueMin (recurring high value); any = at least one; sum = the window total. valueMin is in cents, inclusive. minOccurrences is the minimum count of orders/days.

Per row: occurrences (count), value (window total), minValue/maxValue (smallest/largest occurrence) and lastDate — the diagnostics that let you show why each client qualified. Values are in cents; the window and the day are cut from order_date in the org timezone, like the sales report. 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 experiment 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) — no CSV in the middle.

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
groupBy string The occurrence unit. `order` = one order, one occurrence. `purchase_day` = one day, summing the same-day tickets. Default: `order`.
minOccurrences integer Minimum number of orders/days. Default 1.
valueMin integer Value floor per occurrence, in cents (inclusive). 0 = no floor. Default 0.
valueMode string How `valueMin` applies: `all` = every occurrence ≥ valueMin; `any` = at least one; `sum` = the window total ≥ valueMin. Default: `all`.
status string Order status counted. Default `completed` (only settled sales count toward a value audience). `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",
    "groupBy": "purchase_day",
    "filters": { "minOccurrences": 2, "valueMin": 300000, "valueMode": "all", "status": "completed" },
    "notes": { "occurrence": "...", "valueMode": "...", "scope": "..." }
  },
  "rows": [
    { "client": 363050, "occurrences": 11, "value": 546004833,
      "minValue": 2512579, "maxValue": 166735504, "lastDate": "2026-08-25" }
  ],
  "total": 1339,
  "pagination": { "entries": 100, "currentPage": 1, "totalPages": 14, "isInitial": true, "isEnd": false }
}

Related

Copied to clipboard