Skip to content
TipPage Docs
Esc
↑↓navigate↵open⌘Jpreview

A viewer's sub-reward history

The viewer’s played sub-reward messages, most recent first - the same shape as /tts/history, filtered to this viewer’s sub rewards. Replays by the streamer are excluded; a sub reward still waiting to play shows up in /tts/queue like any other tip. Requires viewers:read.

GET/viewers/{user}/rewards
Authorization
AuthorizationBearer token (tp_live_... or tpat_...) · headerrequired
A TipPage API key (`tp_live_...`, created in Dashboard → Settings → Developer) or an OAuth 2.0 access token (`tpat_...`, see the OAuth guide). Both carry the same scopes and are accepted on every endpoint.
Path parameters
userstringrequired
Which viewer: `<platform>:<id>` (`twitch:123456789`, `kick:123`), a bare numeric id, or a login / display name (case-insensitive, matched on both platforms; URL-encode names with special characters). A bare id is tried on Twitch then Kick - if an account with that id has signed in on both, the answer is `409 ambiguous_viewer`; a name shared by two different people is 409 too, while a name that matches both of ONE person's linked accounts resolves to the one they signed in with most recently. Prefer `platform:id` in automation - it survives renames and can never be ambiguous.
Query parameters
limitinteger
min 1 · max 100 · default: 25
beforestring
Cursor - an `order_id` from a previous page (`next_cursor`). Returns rows strictly older than it.
Responses
200One page of played sub rewards.
viewerViewer
A viewer who has signed in to the tip page. `platform` + `platform_user_id` name the account they signed in with here; `linked_accounts` lists the person's other platform account(s), if they linked any (may be empty). Credits and reward history are read across the whole set.
Show properties
platformstringrequired
Allowed:twitchkick
platform_user_idstringrequired
loginstring | null
display_namestring | null
profile_image_urlstring<uri> | null
subscriber_tierinteger
Their sub tier as last seen (0 = not subscribed).
Allowed:0123
first_signed_in_atstring<date-time>
When they first signed in to this tip page.
last_active_atstring<date-time>
Last account activity seen (profile refreshes included).
linked_accountsobject[]required
The person's OTHER platform accounts - never the one above. Empty when nothing is linked.
Show properties
Array of object
platformstring
Allowed:twitchkick
platform_user_idstring
loginstring | null
display_namestring | null
rewardsHistoryTip[]
Show properties
Array of HistoryTip
order_idstring
namestring
amountnumber | null
messagestring | null
tts_urlstring<uri> | null
is_replayboolean
is_sub_rewardboolean
sourcestring
Where the tip came from: `stripe`, `paypal`, `manual` (dashboard manual tip), `api` (POST /tips), `sub_reward`, `replay`, `test`, `ayupcc`, or `unknown` for tips older than source tracking.
external_sourcestring | null
Developer-API tips only - the `source` label the caller sent (`kofi`, `ayupcc`); `null` for every other source. Says where the tip came from, not whether money moved - see `is_paid`.
external_refstring | null
Developer-API tips only - the caller's own payment reference.
is_paidboolean
Real money changed hands (Stripe, PayPal, or a developer-API tip sent with `paid: true`). `false` for manual tips, free integration tips and sub rewards - those never count toward the streamer's totals.
platformstring | null
Platform of the signed-in donor
Allowed:twitchkicknull
platform_user_idstring | null
The donor's id on that platform
name_was_filteredboolean
message_was_filteredboolean
queued_atstring<date-time>
When the tip entered the queue.
played_atstring<date-time>
When it finished playing on stream.
has_moreboolean
next_cursorstring | null
400Unknown `before` cursor (`bad_cursor`).
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
401Missing or invalid credential (`missing_api_key` / `invalid_api_key`, or `invalid_token` for an expired/revoked OAuth access token).
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
403The key lacks the required scope (`missing_scope`).
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
required_scopestring
404No viewer with that name or id has ever signed in to this tip page (`viewer_not_signed_in`). Signing in on the tip page (Twitch or Kick) is what creates a viewer - until then they can't be looked up or granted credits.
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
409More than one signed-in viewer matches (`ambiguous_viewer`) - two people share that name, or a bare id exists on both platforms. Retry with `<platform>:<id>`.
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
429Rate limit exceeded - check the `RateLimit-*` headers.
errorstring
Request
curl -X GET "https://api.tippage.com/v1/viewers/string/rewards" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "viewer": {
    "platform": "twitch",
    "platform_user_id": "123456789",
    "login": "gigachad42",
    "display_name": "GigaChad42",
    "profile_image_url": "http://example.com",
    "subscriber_tier": 0,
    "first_signed_in_at": "2019-08-24T14:15:22Z",
    "last_active_at": "2019-08-24T14:15:22Z",
    "linked_accounts": [
      {
        "platform": "twitch",
        "platform_user_id": "string",
        "login": "string",
        "display_name": "string"
      }
    ]
  },
  "rewards": [
    {
      "order_id": "string",
      "name": "string",
      "amount": 0,
      "message": "string",
      "tts_url": "http://example.com",
      "is_replay": true,
      "is_sub_reward": true,
      "source": "string",
      "external_source": "string",
      "external_ref": "string",
      "is_paid": true,
      "platform": "twitch",
      "platform_user_id": "string",
      "name_was_filtered": true,
      "message_was_filtered": true,
      "queued_at": "2019-08-24T14:15:22Z",
      "played_at": "2019-08-24T14:15:22Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}