---
search:
  tags:
    - Tipping
    - POST
seo:
  description: >-
    Add a tip that TipPage didn't take payment for. It enters the TTS queue (and
    the media… Reference for the POST /tips endpoint in the TipPage Developer
    API.
sidebar:
  label: Create a tip
  badge: POST
title: Create a tip
type: openapi-operation
---
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`

**Request body** (`application/json`, required)

- `name` (string, required) — The display name shown on stream.
- `amount` (number, required) — Displayed amount, in the streamer's currency.
- `message` (string)
- `media_url` (string<uri>) — Optional video to queue alongside (YouTube supported).
- `media_start_time` (integer) — Video start offset in seconds.
- `source` (string) — 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.
- `paid` (boolean) — Real money was processed on \`source\`. Makes the tip count as revenue (overview, reports, leaderboard, tip goal). Requires \`source\`.
- `reference` (string) — Your own reference for the payment on that platform (a transaction or order id). Requires \`source\`.

Request body example:

```json
{
  "name": "string",
  "amount": 0,
  "message": "string",
  "media_url": "http://example.com",
  "media_start_time": 0,
  "source": "kofi",
  "paid": false,
  "reference": "kofi_txn_8f3a2c"
}
```

**Responses**

- `201` — Tip queued.
- `400` — Validation failed (name/amount/message/media URL).
- `401` — Missing or invalid credential (\`missing\_api\_key\` / \`invalid\_api\_key\`, or \`invalid\_token\` for an expired/revoked OAuth access token).
- `403` — The key lacks the required scope (\`missing\_scope\`).
- `429` — Rate limit exceeded - check the \`RateLimit-\*\` headers.

Response example, 201:

```json
{
  "tip": {
    "order_id": "tip_1755100000000_ab12cd",
    "name": "string",
    "amount": 5,
    "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"
  },
  "media_queued": true
}
```
