Conventions

Envelopes, pagination, rate limits, and error shapes — consistent across every endpoint.

Response envelope

Successful responses wrap the payload in data, with meta present when there’s pagination:

{ "data": [ … ], "meta": { "pagination": { "limit": 50, "offset": 0, "nextOffset": 50 } } }

Errors are flat:

{ "error": "validation_failed", "reason": "from must be an ISO date (YYYY-MM-DD)" }

Pagination

List endpoints take limit (default 50, max 200) and offset. When a page comes back full, meta.pagination.nextOffset tells you where to continue; when it’s null, you’ve reached the end.

Amount sign convention

Bank transaction amounts use the banking convention throughout: positive = money out (expense), negative = money in (income). Financial statements use normal accounting presentation.

This holds no matter how a transaction reached Cherry. A statement’s “deposits” and “withdrawals” columns are mapped to this convention once, at the point Cherry reads the statement, so an uploaded statement and a pushed row are the same shape by the time you read them back.

Currency

Every transaction carries its own currency as a 3-letter ISO 4217 code. Cherry never assumes USD: pushed accounts declare their currency, and uploaded statements are read in whatever currency the statement prints.

Cherry stores what it was given. It does not convert between currencies.

Dates

All dates are ISO YYYY-MM-DD. Transaction queries default to the last 30 days when no range is given.

Rate limits

Limits apply per API key, in three buckets:

Bucket	Applies to	Burst	Sustained
Reads	List and detail GETs	120	3,600/hour
Reports	Trial balance, statements, health score	20	240/hour
Writes	Pushing accounts and transactions, recategorizing	60	240/hour

A 429 includes retryAfterSeconds in the body and a Retry-After header.

Idempotency

Pushed transactions are idempotent: supply your own id per transaction, or omit it and Cherry derives a stable identity from date, amount, and description. Re-sending the same batch never creates duplicates.