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
200

Granted; 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).

401

Missing 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).

403

The key lacks the required scope (missing_scope).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

required_scopestring
404

No 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).

409

More 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).

429

Rate limit exceeded - check the RateLimit-* headers.

errorstring
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.tippage.com/v1/viewers/string/credits/grant' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -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
  }
}