Lists planned expenses on a budget. Pass boxId after get_box / list_boxes to load that box’s expenses (boxes do not nest them). Optional query matches expense names.
GET
/v1/list_expensesQuery
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| budgetId | string | Yes | — | Budget whose planned expenses to list. |
| boxId | string | No | — | Limit results to expenses inside this box. |
| query | string | No | — | Case-insensitive substring match on expense name. |
| limit | number | No | 50 | Max items to return (1–100). |
Response data
| Field | Type | Description |
|---|---|---|
| items | array | Array of planned expenses matching the query. |
| hasMore | boolean | true if truncated by limit. |
Item fields
| Field | Type | Description |
|---|---|---|
| id | string | Id of the planned expense. |
| boxId | string | Id of the parent expense box. |
| boxName | string | Parent box name. |
| name | string | Human-readable name shown in the app. |
| description | string | Free-text description or memo. |
| amount | number | Planned amount. |
| currency | string | ISO 4217 currency code. |
| frequency | string | Expense cadence: monthly, bimonthly, quarterly, triannual, semiannual, or annual. |
| paymentDay | number | Day of month the expense is due (1–31), when set. |
| paymentAnchorMonth | number | Anchor month (1–12) for non-monthly frequencies, when set. |
| icon | string | Icon key when set in the app. |
| iconColor | string | Curated icon circle fill key when set. |
| matchingGroup | string | Optional Transactions Analysis matching-group label when set. |
| sortOrder | number | Sort position within the parent box. |
| isDeleted | boolean | Soft-delete flag when present on the stored document. |
| deletedAt | string | ISO-8601 soft-delete timestamp when present. |
| createdAt | string | Creation timestamp when present (API-created expenses). |
| updatedAt | string | Last update timestamp when present. |