Create a tip

Add a tip that TipPage didn’t take payment for. It enters the TTS queue (and the media queue when media_url is given) and plays like any other tip, with TTS pre-rendered. These tips deliberately skip the word filter (the author is trusted). Fires tip.created with source: "api".

Two independent fields decide how the tip is counted:

source labels where the tip came from - a stable lower-case slug per platform (kofi, youtube-superchat, ayupcc). Reports list one row per distinct source. On its own it makes a free tip: shown and read out on stream, never counted as money.
paid: true says real money was processed on that platform (a Ko-fi payment, a Super Chat, a legacy tipping service you’re bridging). The tip then counts as revenue on the streamer’s overview and in their PDF reports under that source, climbs the leaderboard and moves the tip goal. Requires source. reference is your own transaction id for that payment, shown to the streamer for reconciliation.

Neither field - a manual tip, exactly like the dashboard’s manual-tip form: visible on stream, never in the money totals, itemised separately in reports. Requires tips:create.

POST/tips

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.

Request body

requiredapplication/json

namestringrequired

The display name shown on stream.

max length 22

amountnumberrequired

Displayed amount, in the streamer's currency.

min 0 · max 100000

messagestring

max length 255

media_urlstring<uri>

Optional video to queue alongside (YouTube supported).

media_start_timeinteger

Video start offset in seconds.

min 0 · default: 0

sourcestring

Where the tip came from, as a lower-case slug (`kofi`, `youtube-superchat`, `ayupcc`). A label only - pair it with `paid: true` when money really moved there.

matches ^[a-z0-9][a-z0-9._-]{1,47}$

paidboolean

Real money was processed on `source`. Makes the tip count as revenue (overview, reports, leaderboard, tip goal). Requires `source`.

default: false

referencestring

Your own reference for the payment on that platform (a transaction or order id). Requires `source`.

max length 128

Responses

201Tip queued.

successboolean

order_idstring

media_queuedboolean

Whether a media item was queued alongside.

paidboolean

Whether the tip counts as revenue (you sent `paid: true` with a source).

sourcestring | null

The normalised `source` you sent, or null for a manual tip.

referencestring | null

400Validation failed (name/amount/message/media URL).

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

429Rate limit exceeded - check the `RateLimit-*` headers.

errorstring

Request

curl -X POST "https://api.tippage.com/v1/tips" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "amount": 100000,
  "message": "string",
  "media_url": "http://example.com",
  "media_start_time": 0,
  "source": "kofi",
  "paid": false,
  "reference": "kofi_txn_8f3a2c"
}'

const response = await fetch("https://api.tippage.com/v1/tips", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "name": "string",
  "amount": 100000,
  "message": "string",
  "media_url": "http://example.com",
  "media_start_time": 0,
  "source": "kofi",
  "paid": false,
  "reference": "kofi_txn_8f3a2c"
})
});

import requests

response = requests.post(
    "https://api.tippage.com/v1/tips",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "name": "string",
  "amount": 100000,
  "message": "string",
  "media_url": "http://example.com",
  "media_start_time": 0,
  "source": "kofi",
  "paid": False,
  "reference": "kofi_txn_8f3a2c"
},
)

Response

{
  "success": true,
  "order_id": "api_1755115200000_x1y2z3",
  "media_queued": true,
  "paid": true,
  "source": "string",
  "reference": "string"
}