Returning.AIDevelopers
v1

API reference / Community Analytics

.md

Get loyalty overview

Page through one loyalty summary row per trader in your community, with balances, roles, visits and join date.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/community-analytics/loyalty-overview
Permission
customerSuccess
Retries
Read-only; exact retries are safe

When to use this

  • Load every trader's XP and coin balances into your data warehouse on a daily schedule.
  • Pull the traders who joined your community in a date range, with their loyalty totals.
  • Give your CRM a trader's roles, visit count and lifetime coins spent in the store.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
customerSuccessShown in the dashboard as “Customer Success”

Use a Community API key with customerSuccess, shown in the dashboard as Customer Success, and keep it on your server. The key decides the community, so you only ever see your own traders. A key without the permission gets 401, not 403. Personal API keys are rejected with 401.

Behaviour#

Each row is a trader who has an XP record in your community, so traders who have never earned XP may be missing. Rows are sorted by platform user ID. Read every page up to totalPages: a page can come back with fewer rows than limit before the last page, so a short page doesn't mean you have reached the end.

from and to filter on the join date in first_loyalty_login, and both are inclusive. When either is set, traders with no recorded join date are left out, so the filtered total can be lower than the unfiltered one even for a range that covers all time.

Balances are the values at the moment you read them. XP and coin balances are cut, not rounded, to two decimal places.

Request#

Query parameters#

page#integerOPTIONAL
Page number, starting at 1.

RuleWhole number, 1 or more; default 1

Eg1

limit#integerOPTIONAL
Rows per page.

RuleDefault 100; max 500

Eg100

from#stringOPTIONAL
Only traders who joined your community at or after this moment. Traders with no recorded join date are left out whenever from or to is set.

RuleISO 8601 date-time in UTC, ending in Z

Eg2026-09-01T00:00:00Z

to#stringOPTIONAL
Only traders who joined your community at or before this moment.

RuleISO 8601 date-time in UTC, ending in Z

Eg2026-09-30T23:59:59Z

Headers#

Authorization#stringREQUIRED
Community API key with customerSuccess.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/community-analytics/loyalty-overview?page=1&limit=100&from=2026-09-01T00:00:00Z' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the page in data.data and the totals in data.pagination. A page past the last one returns an empty data.data with the same total. The response holds trader emails, so store it as personal data.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Loyalty overview fetched successfully"

data#objectALWAYS
This page of rows and the paging totals.

Eg{ ... }

data#object[]ALWAYS
One row per trader on this page, ordered by platform user ID. Empty past the last page.

Eg[ ... ]

client_id#stringALWAYS
The trader's platform user ID, as a string.

Eg"3247779"

email#stringALWAYS
The trader's email, or null when the account has none. Treat it as personal data.

RuleEmail format; nullable

Eg"trader@example.com"

current_xp_balance#numberALWAYS
The trader's XP in your community now, cut to two decimal places.

Eg1250

current_coin_balance#numberALWAYS
The trader's coin balance in your community now, cut to two decimal places.

Eg480.5

lifetime_coins_redeemed#numberALWAYS
Coins the trader has spent in your store over all time (price times quantity), not counting failed purchases.

Eg25

roles#string[]ALWAYS
Titles of the trader's roles in your community. Empty when they hold none.

Eg["Member"]

login_count#integerALWAYS
Number of days the trader has a recorded visit to your community.

RuleMin 0

Eg14

first_loyalty_login#stringALWAYS
When the trader joined your community. null when no join date is recorded. This is the date from and to filter on.

RuleDate-time; nullable

Eg"2026-09-01T08:30:00.000Z"

last_loyalty_login#stringALWAYS
The trader's most recent recorded login, or null when none is recorded.

RuleDate-time; nullable

Eg"2026-09-26T09:15:00.000Z"

pagination#objectALWAYS
Paging totals for every row that matches.

Eg{"total": 1, "page": 1, "limit": 100, "totalPages": 1}

total#integerALWAYS
Traders that match, across all pages.

RuleMin 0

Eg1

page#integerALWAYS
The page you asked for.

RuleMin 1

Eg1

limit#integerALWAYS
The page size used.

Rule1-500

Eg100

totalPages#integerALWAYS
Pages at this limit. 0 when nothing matches.

RuleMin 0

Eg1

{
  "status": "success",
  "message": "Loyalty overview fetched successfully",
  "data": {
    "data": [
      {
        "client_id": "3247779",
        "email": "trader@example.com",
        "current_xp_balance": 1250,
        "current_coin_balance": 480.5,
        "lifetime_coins_redeemed": 25,
        "roles": ["Member"],
        "login_count": 14,
        "first_loyalty_login": "2026-09-01T08:30:00.000Z",
        "last_loyalty_login": "2026-09-26T09:15:00.000Z"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "limit": 100,
      "totalPages": 1
    }
  }
}

Errors#

Errors on this endpoint have no machine-readable code; branch on the HTTP status. A validation 400 names the parameter in detail. A 401 carries only message, or status and message.

Fix the request02

400Fix the request
A query value is invalid: page below 1, limit outside 1-500, or from or to not an ISO 8601 date-time ending in Z (an offset such as +08:00 is rejected). detail names the parameter.
401Fix the request
The key is missing (Invalid token), unknown (Invalid API key) or expired, it's a personal key, or it lacks customerSuccess (Your api key does not have permission to access this action). Send Authorization: Bearer <API_KEY> with a Community API key, and add Customer Success in Settings > Integration > API Keys.

Retry with backoff02

429Retry with backoff
Your community has a rate limit for these analytics endpoints, and this caller has used it up for the current window. Wait until the window resets, as shown in the RateLimit header, then retry.
500Retry with backoff
The rows could not be read, or the key could not be checked (Authentication failed). Retry the same request with exponential backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Get loyalty overview endpoint validation error.",
  "detail": {
    "limit": "Number must be less than or equal to 500"
  },
  "solution": "Check your query in request and try again"
}

Next step#

Look up one trader from a row with Get User DataPOST/v1/users/infoUse client_id or email to read the trader's full profile and custom fields.