Account Budgets

• Introduction
• The budget matrix
  • Retrieve the editing matrix for a fiscal year
• Updating budgets
  • Bulk upsert account budgets
• Copying from another fiscal year
  • Copy budgets or actuals from another fiscal year
• Authentication & Permissions

Introduction

Account budgets let you store one expected amount per accounting account per fiscal year. They feed the budget comparison option of the income statement and the editing matrix shown under Accounting → Reports → Budget in the UI.

Budgets are only allowed on posting accounts (types active, passive, revenue, expense). Support and helper accounts are rejected with a 422 response.

Required Permission

All account budget endpoints require the manage budgets permission.

The budget matrix

Retrieve the editing matrix for a fiscal year

get

/fiscal_year/{fiscalYear}/budget

Returns every budgetable account for the tenant, with the current budget row (or null), the actual booked amount from the previous fiscal year, and the actual booked amount for the requested fiscal year so far, ready for editing.

Example response

// HTTP 200 OK
{
    "fiscal_year": {
        "id": "abc123",
        "name": "2026",
        "start_date": "2026-01-01",
        "end_date": "2026-12-31",
        "closed_at": null
    },
    "previous_fiscal_year": {
        "id": "xyz789",
        "name": "2025",
        "start_date": "2025-01-01",
        "end_date": "2025-12-31",
        "closed_at": "2026-03-31T00:00:00.000000Z"
    },
    "accounts": [
        {
            "id": "qr456",
            "number": 3000,
            "name": "Produktionsertrag",
            "full_name": "3000 - Produktionsertrag",
            "type": "revenue",
            "class": "Betrieblicher Ertrag aus Lieferungen und Leistungen",
            "section": "Produktionsertrag",
            "group": "Produktionsertrag",
            "is_active": true,
            "previous_year_actual": 125000.00,
            "current_year_actual": 87340.50,
            "budget": {
                "id": "bdg001",
                "fiscal_year_id": "abc123",
                "account_id": "qr456",
                "amount": "140000.00",
                "notes": null
            }
        }
    ]
}

Updating budgets

Bulk upsert account budgets

put

/fiscal_year/{fiscalYear}/budget

Replaces the full editing state for the given fiscal year in a single transaction. Rows with amount = 0 and no notes are deleted; all other rows are upserted.

Attribute	Type	Description
accounts	Array	Required. List of account rows to upsert.
accounts.*.account_id	String	Required. Hashed ID of an accounting account. Must be a posting account.
accounts.*.amount	Number	Required. Annual budget amount. Zero deletes the row when notes is empty.
accounts.*.notes	String?	Up to 255 characters.

Example request

{
    "accounts": [
        { "account_id": "qr456", "amount": 140000 },
        { "account_id": "qr457", "amount": 0, "notes": "Holding until Q3 review" },
        { "account_id": "qr458", "amount": 0 }
    ]
}

The first row creates or updates the budget; the second is kept because it has a note; the third deletes any existing budget row.

Example response

// HTTP 200 OK
{
    "status": "ok"
}

Errors

• 422 — At least one account_id references a non-posting account (types support, income_statement, balance_sheet).

Copying from another fiscal year

Copy budgets or actuals from another fiscal year

post

/fiscal_year/{fiscalYear}/budget/copy-from/{sourceFiscalYear}

Seeds the target fiscal year's budgets from a source fiscal year, either by reusing its budgeted amounts or by carrying over the actually booked totals.

Attribute	Type	Description
source	String	Required. budget reuses the source fiscal year's budget rows; actuals uses the booked balances from that year.
mode	String	Required. overwrite deletes all existing budget rows in the target year before copying; merge only writes accounts that do not yet have a budget.

Example request

{
    "source": "budget",
    "mode": "merge"
}

Example response

// HTTP 200 OK
{
    "status": "ok"
}

Errors

• 422 — sourceFiscalYear is the same as the target fiscal year.

Authentication & Permissions

Required Permission

All endpoints in this section require the manage budgets permission. Users without it receive a 403 Forbidden response.