# Tipping API

> KickBot API and MCP reference for tipping: tip settings, the tip page, the tip alert widget, tip moderation, the tip queue and earnings.

Source: https://kickbot.com/docs/api/reference/tipping

Use these actions to manage tipping on your channel: the tip page, tip alerts, filters, the queue and your earnings. Billing, payouts, refunds and the Stripe setup are not in the API.

Each action is a REST endpoint under `https://kickbot.com/api/v1` and an MCP tool with the same name. The MCP area name is `tipping`. Use it to load only this area: `https://kickbot.com/api/v1/mcp?areas=tipping`.

A team member needs one of these permissions in Manage Team: **Tipping configuration** or **Tipping moderation**. Some actions need a specific one (the action says so). Owners and admins have every permission. Write actions also need a read and write key or connection. See [Permissions and security](https://kickbot.com/docs/api/start/permissions-and-security).

How the feature works in the dashboard: [Set up tipping](https://kickbot.com/docs/tipping/set-up-tipping), [Tip page](https://kickbot.com/docs/tipping/tip-page), [Tip queue](https://kickbot.com/docs/tipping/tip-queue), [Tip moderation](https://kickbot.com/docs/tipping/tip-moderation).

## Actions

| Tool | REST | Access |
|---|---|---|
| [`get_tipping_status`](#get_tipping_status) | `GET /tipping/status` | Read |
| [`get_tip_queue`](#get_tip_queue) | `GET /tipping/queue` | Read |
| [`get_tip_queue_settings`](#get_tip_queue_settings) | `GET /tipping/queue/settings` | Read |
| [`update_tip_queue_settings`](#update_tip_queue_settings) | `PATCH /tipping/queue/settings` | Write |
| [`resume_tip_queue`](#resume_tip_queue) | `POST /tipping/queue/resume` | Write |
| [`pause_tip_queue`](#pause_tip_queue) | `POST /tipping/queue/pause` | Write |
| [`clear_tip_queue`](#clear_tip_queue) | `POST /tipping/queue/clear` | Write |
| [`approve_tip`](#approve_tip) | `POST /tipping/queue/{id}/approve` | Write |
| [`reject_tip`](#reject_tip) | `POST /tipping/queue/{id}/reject` | Write |
| [`replay_tip`](#replay_tip) | `POST /tipping/transactions/{id}/replay` | Write |
| [`get_tip_moderation_settings`](#get_tip_moderation_settings) | `GET /tipping/moderation` | Read |
| [`update_tip_moderation_settings`](#update_tip_moderation_settings) | `PATCH /tipping/moderation` | Write |
| [`list_blocked_tip_messages`](#list_blocked_tip_messages) | `GET /tipping/moderation/blocked-messages` | Read |
| [`get_tip_widget_settings`](#get_tip_widget_settings) | `GET /tipping/widget` | Read |
| [`update_tip_widget_settings`](#update_tip_widget_settings) | `PATCH /tipping/widget` | Write |
| [`get_tip_page_settings`](#get_tip_page_settings) | `GET /tipping/payment-page` | Read |
| [`update_tip_page_settings`](#update_tip_page_settings) | `PATCH /tipping/payment-page` | Write |
| [`create_tip_banner_upload_url`](#create_tip_banner_upload_url) | `POST /tipping/payment-page/banner-upload` | Write |
| [`list_tip_transactions`](#list_tip_transactions) | `GET /tipping/transactions` | Read |
| [`get_tip_earnings_summary`](#get_tip_earnings_summary) | `GET /tipping/earnings` | Read |

## get_tipping_status

**Get the tipping status.** Start here for tipping. Shows if the Stripe payout account is connected and can receive tips, if tipping is on, and the tip page URL. Connecting Stripe, payouts, and refunds are only in the KickBot dashboard (Tipping > Settings and Earnings), not in the API.

```http
GET /api/v1/tipping/status
```

This has an effect outside your settings (for example on your live stream).

No input fields.

## get_tip_queue

**Get the tip queue.** List the tips waiting to play on stream (newest first), with the queue state (playing or paused, automatic or manual). Each item: id (use it with approve_tip / reject_tip), amount_cents (US cents), tipper_name, message, approval_status (pending = waits for approval, approved = will play), is_replay, is_test, gif_url, tts_audio_url, tts_voice {id, label}, created_at. `recent_tips` are the last 8 tips that played (the dashboard "Recent tips"); play one again with replay_tip and its id.

```http
GET /api/v1/tipping/queue
```

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer | No | Max items to return (1-100, default 50). |
| `offset` (query) | integer | No | Number of items to skip (default 0). |

## get_tip_queue_settings

**Get the tip queue settings.** Get the tip queue settings: tipping on or off, automatic or manual approval, the delay between tips, and if the queue is playing or paused.

```http
GET /api/v1/tipping/queue/settings
```

No input fields.

## update_tip_queue_settings

**Update the tip queue settings.** Change tipping on/off, the queue mode (automatic or manual approval), or the delay between tips. Only the fields you send change. To play or pause the queue use resume_tip_queue / pause_tip_queue.

```http
PATCH /api/v1/tipping/queue/settings
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

| Field | Type | Required | Description |
|---|---|---|---|
| `tipping_enabled` | boolean | No | Viewers can send tips on the tip page. Same switch as tipping_enabled in update_tip_page_settings. |
| `queue_mode` | `"automatic"` or `"manual"` | No | automatic: paid tips play on stream by themselves. manual: each tip waits until you approve it (approve_tip). |
| `queue_delay` | integer | No | Minimum seconds between two tips on stream, 0-100. |

## resume_tip_queue

**Resume the tip queue.** Start playing tips on stream again after pause_tip_queue. Approved tips in the queue start to play.

```http
POST /api/v1/tipping/queue/resume
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it. This has an effect outside your settings (for example on your live stream).

No input fields.

## pause_tip_queue

**Pause the tip queue.** Stop playing tips on stream. New tips still come in and wait in the queue until resume_tip_queue.

```http
POST /api/v1/tipping/queue/pause
```

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream).

No input fields.

## clear_tip_queue

**Clear the tip queue (reject all).** Reject ALL tips that are not paid yet (every pending and approved tip in the queue) and cancel their Stripe payments, so those viewers are NOT charged and the streamer does not get that money. This cannot be undone. Ask the streamer before you use it.

```http
POST /api/v1/tipping/queue/clear
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it. This has an effect outside your settings (for example on your live stream).

No input fields.

## approve_tip

**Approve a tip.** Approve a tip in the queue (get_tip_queue) so it plays on stream with its message and TTS. The viewer is charged when the tip plays. Use it for pending tips when the queue mode is manual.

```http
POST /api/v1/tipping/queue/{id}/approve
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it. This has an effect outside your settings (for example on your live stream).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` (in the path) | integer | Yes | The tip id from get_tip_queue. |

## reject_tip

**Reject a tip.** Reject a tip in the queue (get_tip_queue): it does not play, and its Stripe payment is canceled, so the viewer is NOT charged and the streamer does not get the money. For a replay (is_replay = true) it only removes the replay. This cannot be undone.

```http
POST /api/v1/tipping/queue/{id}/reject
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it. This has an effect outside your settings (for example on your live stream).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` (in the path) | integer | Yes | The tip id from get_tip_queue. |

## replay_tip

**Replay a tip on stream.** Play an approved tip again on stream, with its message, GIF, and TTS. It does not charge the viewer again or move money. Use the id from list_tip_transactions. Only approved tips that already played can be replayed. The replay waits in the tip queue (is_replay = true); reject_tip removes it.

```http
POST /api/v1/tipping/transactions/{id}/replay
```

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 20 per minute.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` (in the path) | integer | Yes | The tip id from list_tip_transactions. |

## get_tip_moderation_settings

**Get the tip moderation settings.** Get the filters that block tips before checkout: profanity, repeated text, links, blocked terms, regex patterns, smart filtering, and AI content filters. A blocked tip is never charged and never plays.

```http
GET /api/v1/tipping/moderation
```

No input fields.

## update_tip_moderation_settings

**Update the tip moderation settings.** Change the tip filters. Only the fields you send change; blocked_terms and regex_patterns replace the whole list. Needs the tipping configuration permission.

```http
PATCH /api/v1/tipping/moderation
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

| Field | Type | Required | Description |
|---|---|---|---|
| `bad_word_filter` | boolean | No | Block messages with strong profanity (AI check). |
| `excessive_repeat_filter` | boolean | No | Block messages with too many repeated characters or words. |
| `url_filter` | boolean | No | Block messages that contain links. |
| `smart_filter_enabled` | boolean | No | Use AI to also catch attempts to get around blocked_terms (changed letters, similar sounds). Beta. |
| `blocked_terms` | array of string | No | Words or phrases to block in the tipper name and the message. Replaces the whole list. Up to 200 entries, 150 characters each. Matching ignores case. |
| `regex_patterns` | array of string | No | JavaScript regular expressions; a tip that matches any of them is blocked. Replaces the whole list. Example: "discord\\.gg/\\w+". |
| `ai_filters` | object | No | AI content filters. Send only the filters you want to change. |

## list_blocked_tip_messages

**List blocked tip messages.** List tips that the moderation filters blocked, newest first: amount_cents, message, reason, created_at.

```http
GET /api/v1/tipping/moderation/blocked-messages
```

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer | No | Max items to return (1-100, default 50). |
| `offset` (query) | integer | No | Number of items to skip (default 0). |

## get_tip_widget_settings

**Get the tip widget settings.** Get the on-stream tip widget settings. The widget URL for OBS is not in the API: it contains a secret key. The streamer copies it from Tipping > Widget in the KickBot dashboard.

```http
GET /api/v1/tipping/widget
```

No input fields.

## update_tip_widget_settings

**Update the tip widget settings.** Change how tips look on stream: text, animation, colors, background, and TTS volume. Only the fields you send change. Open widgets reload the settings at once.

```http
PATCH /api/v1/tipping/widget
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | boolean | No | Show the tip message text on the widget while the tip plays. |
| `animation` | `"none"` or `"fade"` or `"slide-left"` or `"slide-right"` or `"slide-top"` or `"slide-bottom"` | No | How the tip message appears. Default fade. |
| `text_size` | integer | No | Font size in pixels, 24-60. Default 24. |
| `text_color` | string | No | Text color as a hex code, for example #FFFFFF. |
| `background` | boolean | No | Show a dark background behind the text. Default true. |
| `background_opacity` | integer | No | Background opacity in percent, 0-100. Default 100. |
| `show_sender_amount` | boolean | No | Show the tipper name and the amount. Default true. |
| `tts_volume` | integer | No | Volume of the tip TTS audio in percent, 0-100. Default 70. |

## get_tip_page_settings

**Get the tip page settings.** Get the public tip page settings (kickbot.com/tips/<name>): on/off, amounts in US cents, presets, message length, allowed TTS voices, GIFs, test mode, custom URL, and banner.

```http
GET /api/v1/tipping/payment-page
```

No input fields.

## update_tip_page_settings

**Update the tip page settings.** Change the tip page. Only the fields you send change. Amounts are US cents: the minimum is $1-$499, the maximum up to $500, and the suggested amount and presets must be between them. custom_slug needs Premium.

```http
PATCH /api/v1/tipping/payment-page
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it. This has an effect outside your settings (for example on your live stream).

| Field | Type | Required | Description |
|---|---|---|---|
| `tipping_enabled` | boolean | No | Viewers can send tips on the tip page. |
| `custom_message` | string | No | Text shown on the tip page, for example "Thanks for the support!". |
| `minimum_amount_cents` | integer | No | Smallest tip in US cents, 100-49900 ($1-$499). Example: 500 = $5.00. |
| `maximum_amount_cents` | integer | No | Largest tip in US cents, 100-50000 ($1-$500). |
| `suggested_amount_cents` | integer | No | Amount filled in by default on the tip page, in US cents. Must be between the minimum and the maximum. |
| `payment_presets_cents` | array of integer | No | Up to 5 quick-pick amounts in US cents, each between the minimum and the maximum. Replaces the whole list. |
| `max_message_length` | integer | No | Max characters in a tip message, 1-150. Default 150. |
| `tts_voice_mode` | `"all"` or `"official"` or `"custom"` | No | Which TTS voices tippers can pick: all voices, official voices only (Premium), or the list in tts_voice_ids. |
| `tts_voice_ids` | array of integer | No | TTS voice ids tippers can pick when tts_voice_mode is custom: any public library voice or your own clone (voice_id from list_tts_library_voices). Premium voices work only on Premium. Replaces the whole list. |
| `gifs_allowed` | boolean | No | Tippers can attach a GIF. |
| `read_username` | boolean | No | TTS reads "<name> tipped $5" before the message. |
| `test_mode_active` | boolean | No | Test mode: no real payments; use it to see how tips look on stream. Turn it off before going live. |
| `custom_slug` | string | No | Premium only. Custom tip page address: kickbot.com/tips/<custom_slug>. 4-50 characters: letters, numbers, - and _. Saved in lower case. |
| `banner_enabled` | boolean | No | Show the uploaded banner image on the tip page. Set true after you upload a banner (create_tip_banner_upload_url). Set false to remove the banner. |

## create_tip_banner_upload_url

**Get an upload URL for the tip page banner.** Step 1 of 2 to set the tip page banner. Send the image type and size; returns upload_url, which only accepts that exact type and size. Upload the image with HTTP PUT to upload_url within 30 minutes: body = the raw image bytes, with the headers in `headers` (Content-Type must be exactly content_type; the body must be exactly size_bytes long). Use a wide image (4:1, for example 1200x300). Allowed types: image/png, image/jpeg, image/gif, image/webp. Max size: 10 MiB (10485760 bytes). Step 2: call update_tip_page_settings with banner_enabled: true. A new upload replaces the old banner.

```http
POST /api/v1/tipping/payment-page/banner-upload
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

| Field | Type | Required | Description |
|---|---|---|---|
| `content_type` | string | Yes | MIME type of the image: image/png, image/jpeg, image/gif, image/webp. |
| `size_bytes` | integer | Yes | Image size in bytes, max 10 MiB. |

## list_tip_transactions

**List tip transactions.** List received tips, newest first (test tips are not included). status is what the earnings page shows: approved, pending, rejected, refunded, disputed, expired, canceled, failed. payment_collected tells if the money was taken. Amounts are US cents before fees. Read only: refunds are only in the dashboard. Use replay_tip to play a tip again.

```http
GET /api/v1/tipping/transactions
```

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer | No | Max items to return (1-100, default 50). |
| `offset` (query) | integer | No | Number of items to skip (default 0). |

## get_tip_earnings_summary

**Get the tip earnings summary.** The numbers on the earnings page: Stripe balances (pending, available, in transit; in the smallest unit of `currency`, for example cents), tip counts for 7 days, 30 days, and all time, and estimated earnings per day for the last 30 days after fees (8.9% + $0.30 per tip). Read only: payouts are only in the dashboard.

```http
GET /api/v1/tipping/earnings
```

This has an effect outside your settings (for example on your live stream).

No input fields.