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

Grant credits

Grants sub-reward credits to a signed-in viewer - the same operation as the dashboard’s grant form; the credits appear on the viewer’s tip page immediately. Credits can only be granted to viewers who have signed in at least once: an unknown name or id answers 404 viewer_not_signed_in, and nothing is granted. Requires viewers:manage.

POST/viewers/{user}/credits/grant
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.
Request body
requiredapplication/json
amountintegerrequired
Credits to grant.
min 1 · max 100
Responses
200Granted; the fresh balance is returned.
successboolean
grantedinteger
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
creditsCreditBalance
A viewer's sub-reward credit balance.
Show properties
availableinteger
Credits spendable right now.
totalinteger
Credits ever granted.
usedinteger
Credits already spent.
400`amount` isn't an integer from 1 to 100 (`bad_request`).
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 POST "https://api.tippage.com/v1/viewers/string/credits/grant" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 1
}'
Response
{
  "success": true,
  "granted": 0,
  "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"
      }
    ]
  },
  "credits": {
    "available": 0,
    "total": 0,
    "used": 0
  }
}