Sign in

Customer RFM by acquisition cohort — new customers / sign-ups per day

GET https://{organization}.myguper.com/api/register/report/rfm-cohort/{dateStart}/{dateEnd}

Customer RFM aggregated by acquisition cohort — how many customers were acquired in each month (or at each store), and what they are worth over their lifetime — in a single call. It is the RFM base, grouped: instead of paging ~hundreds of thousands of per-customer rows and grouping client-side, this returns the cohort rollup at once.

A cohort is cut by the first-purchase date (firstPurchaseDate). Group by month (acquisition month), firstStore (acquisition store), or both. Per cohort you get clients, lifetimeValue and avgValue (spend), avgOrders (frequency), avgCadenceDays (repeat interval, only over customers with 2+ orders) and avgDaysWithoutPurchase (recency today).

Values are in cents. The month is cut in the organization timezone, so cohorts line up with the sales report by (month, store). total reconciles with the sum of the rows by construction.

Read the semantics carefully: store is the acquisition store and lifetimeValue is the customer's org-wide lifetime spend (across every store), not the store's sales — "customers acquired at store X and what they spent everywhere". For store sales use order.report.sales; do not mix them.

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 acquisition window (YYYY-MM-DD), inclusive — customers whose first purchase falls on/after this date.
dateEnd * string End of the acquisition window (YYYY-MM-DD), inclusive.

Query parameters

Name Type Description
groupBy string How to break the cohorts down. One of `month` (acquisition month), `firstStore` (acquisition store), or a comma list. Default: `month`.

Responses

{
  "meta": {
    "unit": "cents", "timezone": "Etc/GMT+6",
    "groupBy": ["month"],
    "window": { "dateStart": "2025-01-01", "dateEnd": "2025-06-30" }
  },
  "rows": [
    { "month": "2025-01", "clients": 16131, "lifetimeValue": 4676422124, "avgValue": 289903,
      "avgOrders": 1.50, "avgCadenceDays": 98.1, "avgDaysWithoutPurchase": 435 },
    { "month": "2025-02", "clients": 8890, "lifetimeValue": 2766238779, "avgValue": 311163,
      "avgOrders": 1.49, "avgCadenceDays": 94.2, "avgDaysWithoutPurchase": 410 }
  ],
  "total": {
    "clients": 74775, "lifetimeValue": 24488794816, "avgValue": 327500,
    "avgOrders": 2.49, "avgCadenceDays": 78, "avgDaysWithoutPurchase": 366
  }
}

Related

Copied to clipboard