# Working with data

Field formats, list pages, and how goals, top donors and totals are calculated.

## Formats

- Money: `{"value": "500.00", "currency": "RUB"}`. `value` is a string with two decimal places, `currency` is an ISO 4217 code. Don't convert `value` to a floating-point number.
- Time: RFC 3339 in UTC, for example `2026-11-09T10:15:30Z`. Fractions of a second can appear.
- Identifiers are strings with a prefix: `str_…`, `don_…`, `goal_…`.
- Skip unknown fields and new values in `source`, `status` and `provider`: they appear without a new API version.

## Pages

Donations and goals come in pages: `{"items": [...], "nextCursor": "..."}`. To get the next page, pass `nextCursor` in the `cursor` parameter. `nextCursor: null` means this is the last page. `limit` is 1 to 100 records, 20 by default. Pages go from newest to oldest, with no gaps or repeats. New donations and new moderation statuses come only in a new request without `cursor`. Donations also have the `since` parameter: you get donations created at or after that moment. An empty `"items": []` with status 200: [see FAQ](https://developers.donatty.com/en/faq.md#why-did-i-get-an-empty-list). Top donors returns up to `limit` entries in one page, without `nextCursor`; 10 by default.

## Why the goal amount differs from the widget

`raised` includes the amount you started the goal with (the «Начать сбор с» (Start collecting from) field) and every Donatty donation to the goal, including ones rejected by moderation. The API does not count Donation Alerts goals or widget settings.

## Top donors and totals for a period

We count all connected sources and convert to rubles. Donations rejected by moderation are included.

| `period` | What is counted |
|---|---|
| `DAY` | today from 00:00 |
| `WEEK` | this week from Monday |
| `MONTH` | this month from the 1st |
| `YEAR` | this year from January 1 |
| `ALL_TIME` | all time; the default |

Boundaries follow the time zone in `timeZone`, `Europe/Moscow` by default. In the response, `from` is the start of the period and `to` is the start of the next one: a donation created exactly at `to` is not included. For `ALL_TIME`, `to` is the moment of the response.

The API has no balance and no withdrawals.
