Spending by category (?month= widget, or ?preset/start/end range)
const url = 'https://api.tovarifinancial.com/reports/spending-by-category?month=2026-07&preset=this_month&start=2026-07&end=2026-07&shape=compact&include=kpis';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.tovarifinancial.com/reports/spending-by-category?month=2026-07&preset=this_month&start=2026-07&end=2026-07&shape=compact&include=kpis' \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Month, ‘YYYY-MM’
Example
2026-07Widget mode: month ‘YYYY-MM’
Range preset (mutually exclusive with start/end)
Month, ‘YYYY-MM’
Example
2026-07Range start month ‘YYYY-MM’
Month, ‘YYYY-MM’
Example
2026-07Range end month ‘YYYY-MM’
Opt into the compact widget shape. Omit for the legacy ?month= widget or the preset/start/end range shape. Any value other than the one listed is rejected with 400.
Opt-in extra blocks on the compact response. Only supported with shape=compact; an unknown value, or this parameter on the legacy/range paths, is rejected with 400.
Comma-separated account UUIDs to scope the report to. Omit for all accounts. A malformed value is rejected with 400 — it is never dropped to an unfiltered report.
Set to ‘1’ or ‘true’ to restrict the expense side to budgeted expense categories. Never applied to income. Any other value is treated as false. Not accepted together with shape=compact — that combination is a 400, never a silently ignored filter.
Responses
Section titled “Responses”Spending-by-category (widget or range shape)
object
object
object
System_lookups id in the budget_color set; resolve via GET /lookups.
System_lookups id in the budget_icon set; resolve via GET /lookups. Non-null when present — budget_categories.icon_id is NOT NULL and the statement inner-joins the category.
SIGNED net outflow (KAN-697): negative when the category took in more than it paid out.
Server-computed 0-1 donut share. Denominator is the sum of max(0, spentCents) over ALL rows in the window (the named rows AND the rolled-up ‘others’ tail). Null when the row cannot own a share: a net-inflow row (spend is SIGNED since KAN-697) or a non-positive denominator. Clients must render the server value and never re-derive it.
The rolled-up tail beyond the top 8. Carries NO category id/name/colour/icon — attributing one tenant category to an N-category rollup would misstate the data.
object
Integer minor units (cents)
Server-computed 0-1 donut share. Denominator is the sum of max(0, spentCents) over ALL rows in the window (the named rows AND the rolled-up ‘others’ tail). Null when the row cannot own a share: a net-inflow row (spend is SIGNED since KAN-697) or a non-positive denominator. Clients must render the server value and never re-derive it.
Examplegenerated
{ "data": { "categories": [ { "categoryId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example", "colorId": "example", "iconId": "example", "spentCents": 1, "sharePct": 1 } ], "others": { "count": 1, "spentCents": 1, "sharePct": 1 } }, "message": "example", "requestId": "example", "timestamp": "2026-04-15T12:00:00Z"}Validation failed — see errorCode / fieldErrors
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Missing, invalid, or expired bearer token
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend.
object
Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.
object
Active policy versions the user has not yet accepted.
object
True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.
Example
{ "errorCode": "EMAIL_NOT_VERIFIED"}Internal error (no internal detail leaked)
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}