Creates a budget (max 3 owned for Free, 20 for Pro/Ultra). Required: name, baseCurrency, monthlyNetIncome, refillDay. Omit boxes for an empty shell, or pass nested boxes / expenses for a one-shot import (max 3000 nested items; 30 boxes / budget; 100 expenses / box).
POST
/v1/create_budgetBody
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| idempotencyKey | string | Yes | — | Client-generated key (1–128 chars: letters, digits, . _ : -). Same key + same body replays; different body returns 409. Prefer Idempotency-Key HTTP header when calling the Tools API. |
| name | string | Yes | — | Display name for the new budget (max 100 characters). |
| baseCurrency | string | Yes | — | ISO 4217 currency code for the budget. |
| monthlyNetIncome | number | Yes | — | Monthly net income in base currency (0–3000000000). |
| refillDay | number | Yes | — | Day of month (1–31) when unallocated refill happens. |
| city | string | No | — | Optional city label for cost-of-living context (max 100 characters). |
| unallocatedAmount | number | No | 0 | Starting unallocated balance in base currency (0–1000000). |
| boxes | array | No | — | Optional nested boxes, each with name and optional expenses[], for a one-shot import (max 3000 nested items total). |
No silent defaults for required fields — omitting them returns 400. At the budget cap returns resource_limit.
Response data
| Field | Type | Description |
|---|---|---|
| id | string | Id of the newly created budget. |
| name | string | Human-readable name shown in the app. |
| baseCurrency | string | ISO 4217 currency code for the budget. |
| refillDay | number | Day of month for refill (1–31). |
| city | string | Optional city used for cost-of-living context; may be null. |
| boxes | array | Present when nested boxes were created (ids + nested expenses). |