# 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`).

## 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

- `200` — OK
- `400` — A parameter is invalid, or the key was sent in the request address: [`invalid_parameter`](https://developers.donatty.com/en/errors/invalid_parameter.md), [`token_in_query`](https://developers.donatty.com/en/errors/token_in_query.md)
- `401` — The key is missing, unknown, deleted or expired: [`missing_token`](https://developers.donatty.com/en/errors/missing_token.md), [`invalid_token`](https://developers.donatty.com/en/errors/invalid_token.md), [`token_expired`](https://developers.donatty.com/en/errors/token_expired.md)
- `403` — Wrong kind of key, or the key lacks the `donations:read` scope. The public key never has it: [`wrong_token_type`](https://developers.donatty.com/en/errors/wrong_token_type.md), [`insufficient_scope`](https://developers.donatty.com/en/errors/insufficient_scope.md)
- `429` — Rate limit exceeded: [`rate_limited`](https://developers.donatty.com/en/errors/rate_limited.md)
- `500` — The request failed on our side: [`internal_error`](https://developers.donatty.com/en/errors/internal_error.md)
- `503` — The API is temporarily unavailable: [`service_unavailable`](https://developers.donatty.com/en/errors/service_unavailable.md)

## Example response

```json
{
  "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

### DonationPage

| Field | Type | Description |
|---|---|---|
| `items` | list `Donation` |  |
| `nextCursor` | string or null | Pass as `cursor` to get the next page; `null` — last page. |

### 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. |

### Money

| Field | Type | Description |
|---|---|---|
| `value` | string | Decimal amount with two fraction digits. |
| `currency` | string | ISO 4217 code. |

### 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. |
