Donations
GET /v1/donations · Secret key · scope donations:read
Your donations, newest first: from Donatty and from Donation Alerts when it is connected. Without a filter you get every donation with its full text, including ones rejected by moderation or still waiting for a decision. To get only what can be shown on stream, add moderation=PASSED,NONE. The response has no donor contacts, order or service fee; of the payment details it has only feeCompensation (the extra amount the donor paid to cover the fee) and paymentMethod (CARD, SBP or null).
Loading the reference…
Parameters, responses and fields as tables
Parameters
Section titled “Parameters”| Name | In | Type | Description |
|---|---|---|---|
limit |
query | integer, 1–100, default 20 |
How many records to return per page: 1 to 100, 20 by default. |
cursor |
query | string | nextCursor from the previous response; returns the next page. |
since |
query | string (date-time) | Only donations created at or after this moment, for example 2026-11-09T10:00:00Z. |
source |
query | list of strings, values: DONATTY, DONATION_ALERTS |
Which sources to return, comma-separated. Without it, all sources. |
moderation |
query | list of strings, values: PENDING, PASSED, BLOCKED, NONE |
Which moderation statuses to return, comma-separated. For showing on stream use PASSED,NONE. Without it you get every donation, rejected ones included. |
Responses
Section titled “Responses”200— OK400— A parameter is invalid, or the key was sent in the request address:invalid_parameter,token_in_query401— The key is missing, unknown, deleted or expired:missing_token,invalid_token,token_expired403— Wrong kind of key, or the key lacks thedonations:readscope. The public key never has it:wrong_token_type,insufficient_scope429— Rate limit exceeded:rate_limited500— The request failed on our side:internal_error503— The API is temporarily unavailable:service_unavailable
Example response
Section titled “Example response”{ "items": [ { "id": "don_5d2e8f31-6a47-4c19-9b0e-7f3a2d1c8e46", "createdAt": "2026-11-09T10:21:47Z", "source": "DONATTY", "donorName": "Алексей", "message": "Спасибо за стрим!", "amount": { "value": "500.00", "currency": "RUB" }, "feeCompensation": { "value": "27.00", "currency": "RUB" }, "paymentMethod": "CARD", "goal": null, "moderation": { "status": "PASSED", "deadline": null }, "media": null }, { "id": "don_0f6e2a4c-91b3-4d7a-8c5e-3b2a1f0e9d84", "createdAt": "2026-11-09T10:15:30.123456Z", "source": "DONATTY", "donorName": "Alex", "message": "Thanks for the stream!", "amount": { "value": "500.00", "currency": "RUB" }, "feeCompensation": null, "paymentMethod": "SBP", "goal": { "id": "goal_7e3a9c10-4b2d-4f8e-a1c6-0d9b8e7f6a52", "title": "New microphone" }, "moderation": { "status": "PENDING", "deadline": "2026-11-09T10:16:30Z" }, "media": { "title": "Song of the day", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "provider": "YOUTUBE", "durationSeconds": 212, "moderation": { "status": "PENDING", "deadline": "2026-11-09T10:16:30Z" } } }, { "id": "don_3c9d7b21-5e84-4a6f-b0d2-8e1f4a7c6b35", "createdAt": "2026-11-09T10:02:11Z", "source": "DONATTY", "donorName": "Anonymous", "message": "This text was rejected by moderation but is returned in full.", "amount": { "value": "150.50", "currency": "RUB" }, "feeCompensation": null, "paymentMethod": "CARD", "goal": null, "moderation": { "status": "BLOCKED", "deadline": null }, "media": null }, { "id": "don_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "createdAt": "2026-11-09T09:58:00Z", "source": "DONATION_ALERTS", "donorName": "Maria", "message": "Hi from Donation Alerts", "amount": { "value": "5.00", "currency": "USD" }, "feeCompensation": null, "paymentMethod": null, "goal": null, "moderation": { "status": "NONE", "deadline": null }, "media": null } ], "nextCursor": "MTc5NDIxODI4MDAwMDAwMC45YTFiMmMzZC00ZTVmLTRhNmItOGM3ZC0wZTFmMmEzYjRjNWQ"}Schemas
Section titled “Schemas”DonationPage
Section titled “DonationPage”| Field | Type | Description |
|---|---|---|
items |
list Donation |
|
nextCursor |
string or null | Pass as cursor to get the next page; null — last page. |
Donation
Section titled “Donation”| Field | Type | Description |
|---|---|---|
id |
string | Donation identifier, don_…. |
createdAt |
string (date-time) | When the donation was created; for a Donatty donation, when the payment was confirmed. |
source |
string, values: DONATTY, DONATION_ALERTS |
Where the donation came from: DONATTY or DONATION_ALERTS. |
donorName |
string | The name the donor entered. If they left it empty, a Donatty donation has Anonymous. |
message |
string | The donor’s full message; an empty string if they wrote nothing. Widget filters are not applied. |
amount |
Money |
The donation amount in its currency, without the donor’s extra payment for the fee. |
feeCompensation |
Money or null |
The extra amount the donor paid to cover the service fee, in the currency of amount; the donor was charged amount plus feeCompensation. null when the donor did not pay it, and always for DONATION_ALERTS. |
paymentMethod |
string, values: CARD, SBP or null |
How the donor paid: SBP (Faster Payments System) or CARD — every other way, including Apple Pay and Google Pay and older donations with no recorded method. null for DONATION_ALERTS. |
goal |
object or null | The goal the donation went to: id and title. null when there is none. |
moderation |
Moderation |
Moderation of the message: status and deadline. |
media |
object or null | The video attached to the donation: title, url, provider, durationSeconds and its own moderation. null when there is none. |
| Field | Type | Description |
|---|---|---|
value |
string | Decimal amount with two fraction digits. |
currency |
string | ISO 4217 code. |
Moderation
Section titled “Moderation”| Field | Type | Description |
|---|---|---|
status |
string, values: PENDING, PASSED, BLOCKED, NONE |
PENDING — moderation in progress; PASSED — approved (including «Повторить на стриме» (Repeat on stream)); BLOCKED — rejected; NONE — no moderation (disabled, nobody online, Donation Alerts). |
deadline |
string (date-time) or null | Only for PENDING: when the default decision applies. |