GET analytics customers

Endpoint

GET /public-api/v1/analytics/customers

Purpose

Returns top customers by paid-sale spend in the selected date range.

Authentication

Required.

Parameters

• storeIds: optional branch filter.
• from: optional ISO timestamp.
• to: optional ISO timestamp.
• limit: optional row limit, default 100, maximum 100.

Response fields

Each row includes safe customer profile fields, revenue, txCount, avgOrderValue, firstPurchaseAt, and lastPurchaseAt.

Customer phone, email, birthday, document ID, member number, prescriptions, and notes are not returned.

Example request

curl "https://api.klupos.com/public-api/v1/analytics/customers?from=2026-06-01T00:00:00.000Z&to=2026-06-24T23:59:59.999Z" \
  -H "Authorization: Bearer klu_live_replace_me"

Example response

{
  "data": [
    {
      "id": "customer-id",
      "firstName": "Mali",
      "lastName": "S.",
      "type": "MEMBER",
      "region": "Bangkok",
      "revenue": 9200,
      "txCount": 7,
      "avgOrderValue": 1314.29,
      "firstPurchaseAt": "2026-06-02T09:30:00.000Z",
      "lastPurchaseAt": "2026-06-23T12:15:00.000Z"
    }
  ]
}

Common errors

• 400: invalid date range, limit, or store UUID.
• 401: invalid key.
• 403: requested storeIds are outside the organization.
• 429: rate limit exceeded.

AI-agent notes

Use this endpoint for top spender dashboards and customer ranking questions.