Get Loyalty Overview

What this endpoint does

Returns a read-only, paginated loyalty summary for the whole community associated with the Bearer API key. It returns one row per matching client on the requested page; it is not a single-user lookup.

Use it for:

customer-success and loyalty reporting;

scheduled community exports;

reconciliation of XP, coin balances, redemptions, roles, and loyalty visits.

The API key determines the community automatically. Do not send a community ID. This endpoint does not change balances, users, roles, or redemption records.

Quick start

Authentication and permission

Use a community API key in the Authorization header:

The key must be active, scoped to the intended community, and include the customerSuccess permission. Missing, invalid, expired, or under-permissioned keys currently return HTTP 401.

Pagination and date filtering

page is 1-based and defaults to 1.

limit defaults to 100 and cannot exceed 500.

from and to are optional ISO 8601 date-times. They filter by the client's community membership join timestamp, inclusively.

The endpoint does not currently support filtering by email or client_id.

Example with an inclusive date window:

Follow data.pagination until page reaches totalPages. An empty result is successful and returns HTTP 200 with data.data: [].

Response fields

Field	Meaning
`client_id`	Internal Returning.AI member ID represented as a string; unchanged.
`hashed_client_id`	Optional current external identifier from the community's active custom `client_id` text field; omitted when unavailable.
`email`	Client email when available. Treat as personal data.
`current_xp_balance`	Current XP balance.
`current_coin_balance`	Current loyalty coin balance.
`lifetime_coins_redeemed`	Lifetime number of coins redeemed through the Returning.AI store.
`roles`	Community role titles currently resolved for the client.
`login_count`	Count of recorded daily loyalty visits.
`first_loyalty_login`	Community membership join timestamp used by `from` and `to`; may be `null`.
`last_loyalty_login`	Most recent recorded application login timestamp; may be `null`.

External client identifier

hashed_client_id is an optional string on each row in data.data. It contains the existing external identifier from the community's active custom client_id single-line-text field. Returning.AI does not compute a new hash and does not relabel another custom identifier field.

If that field or its value is missing, blank, null, or non-string, hashed_client_id is omitted rather than returned as null or an empty string. Treat the value as an opaque identifier; do not assume a particular hash algorithm, length, or format.

The identifier is community-scoped and reflects the member's current profile value. Historical log rows are enriched with that current value, not an event-time snapshot.

Loyalty overview keeps client_id as the internal Returning.AI member ID represented as a string. User logs retain their existing fields and do not introduce an internal client_id where none was previously present.

Authentication, permissions, request filters, pagination, balances, and event deltas are unchanged.

Errors and recovery

400: Fix invalid pagination or date-time query values. page must be at least 1; limit must be between 1 and 500.

401: Check that the Bearer key is present, valid, active, scoped to the correct community, and has customerSuccess permission. Do not retry unchanged credentials repeatedly.

429: The community request limit was exceeded. Inspect the RateLimit response header and retry after the indicated window resets.

500: Retry with bounded backoff. If the error persists, contact Returning.AI support with the request time and non-sensitive request details.

Retry safety and privacy

This is a read-only request, so retrying the same page is safe. Export pages sequentially and use the pagination metadata rather than assuming a fixed community size. Responses contain client identifiers, emails, balances, roles, and activity timestamps; store and transmit them according to your customer-data controls.

Gotchas

from and to filter the community membership join timestamp, not the last login or redemption date.

A range where from is later than to currently returns an empty successful result; validate the range in your client.

Balances and lifetime redemption values are numeric and may contain decimals even when an example contains whole numbers.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://api.returning.ai/v1/community-analytics/loyalty-overview?page=1&limit=100&from=2026-01-01T00%3A00%3A00.000Z&to=2026-01-31T23%3A59%3A59.999Z' \ --header 'Authorization: Bearer <token>'

{ "status": "success", "message": "Loyalty overview fetched successfully", "data": { "data": [ { "client_id": "123456", "email": "client@example.com", "current_xp_balance": 2450.5, "current_coin_balance": 380.25, "lifetime_coins_redeemed": 1250, "roles": [ "Client" ], "login_count": 42, "first_loyalty_login": "2026-01-05T08:30:00.000Z", "last_loyalty_login": "2026-08-16T14:22:10.000Z", "hashed_client_id": "external-client-hash" } ], "pagination": { "total": 224, "page": 1, "limit": 100, "totalPages": 3 } } }

What this endpoint does#

Quick start#

Authentication and permission#

Pagination and date filtering#

Response fields#

External client identifier#

Errors and recovery#

Retry safety and privacy#

Gotchas#

Request

Responses