Fiscal Year

• Introduction
  • Fiscal Year Types
• Allowed query parameters
• Retrieve a fiscal year
• List fiscal years
• Generate account sheets
• Retrieve account sheets download URL
• Error responses
• Common use cases

Introduction

Fiscal years define the accounting periods for an organization's financial reporting. Each fiscal year has a defined start and end date and can be in an open or closed state. Closed fiscal years cannot be modified to maintain financial data integrity.

Fiscal Year Types

Type	Description
full_year	Standard 12-month fiscal year (365/366 days)
short_year	Fiscal year shorter than a full calendar year
long_year	Fiscal year spanning multiple calendar years

Allowed query parameters

Filters

Filter	Type	Description
open	Boolean	Filter to show only open (unclosed) fiscal years
closed	Boolean	Filter to show only closed fiscal years

Sorting

start_date, closed_at

Appends

checklist - Fiscal year closing checklist (requires MANAGE_ACCOUNTING permission)

Retrieve a fiscal year

get

/fiscal_year/{id}

Example response

// HTTP 200 OK
{
    "id": "k9mQ2rLnVx",
    "name": "2024",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "closed_at": null,
    "is_closed": false,
    "is_open": true,
    "is_current": true,
    "type": {
        "name": "FullYear",
        "value": "full_year"
    }
}

Example response with checklist

// HTTP 200 OK
{
    "id": "k9mQ2rLnVx",
    "name": "2023",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31",
    "closed_at": "2024-02-15T09:30:00.000000Z",
    "is_closed": true,
    "is_open": false,
    "is_current": false,
    "type": {
        "name": "FullYear",
        "value": "full_year"
    },
    "checklist": {
        "balance_sheet_profit_loss_posted": true,
        "income_statement_profit_loss_posted": false,
        "vat_periods_status": {
            "Q1 2023": true,
            "Q2 2023": true,
            "Q3 2023": true,
            "Q4 2023": false
        }
    }
}

List fiscal years

get

/fiscal_year

The list endpoint accepts the same parameters as in Retrieve a fiscal year and returns a paginated array of the same fiscal year object in the data property.

Example request

GET /fiscal_year?filter[open]=1&sort=-start_date

Example response

// HTTP 200 OK
{
    "data": [
        {
            "id": "k9mQ2rLnVx",
            "name": "2024",
            "start_date": "2024-01-01",
            "end_date": "2024-12-31",
            "closed_at": null,
            "is_closed": false,
            "is_open": true,
            "is_current": true,
            "type": {
                "name": "FullYear",
                "value": "full_year"
            }
        },
        {
            "id": "m3nR5tPqWz",
            "name": "2023 - 2024",
            "start_date": "2023-07-01",
            "end_date": "2024-06-30",
            "closed_at": "2024-08-15T14:45:00.000000Z",
            "is_closed": true,
            "is_open": false,
            "is_current": false,
            "type": {
                "name": "LongYear",
                "value": "long_year"
            }
        }
    ],
    "links": {
        "first": "/fiscal_year?page=1",
        "last": "/fiscal_year?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "/fiscal_year",
        "per_page": 25,
        "to": 2,
        "total": 2
    }
}

Generate account sheets

post

/fiscal_year/{id}/account-sheets

Generates a PDF account sheet (Kontoauszug) for every balance sheet account and every account with journal entries in the fiscal year, and packages them into a ZIP archive. Requires the edit fiscal_year permission.

For an open fiscal year (or a closed one without an existing archive) the work runs as a queued batch. The response carries the batchId; progress and completion are broadcast on the member channel as batch.progress.{batchId} and batch.finished.{batchId}, and the finished event's data.sheetsUrl holds a temporary download URL (valid for 5 minutes).

// HTTP 200 OK
{
    "batchId": "9d2f7c1e-3b0a-4f5e-9c8d-1a2b3c4d5e6f",
    "sheetsUrl": null
}

For a closed fiscal year whose archive already exists, no batch is started and the download URL is returned directly:

// HTTP 200 OK
{
    "batchId": null,
    "sheetsUrl": "https://…/Kontoauszüge.zip?X-Amz-Expires=300&…"
}

Retrieve account sheets download URL

get

/fiscal_year/{id}/account-sheets

Returns a temporary download URL (valid for 5 minutes) for the most recently generated account sheets archive, or null when none has been generated yet. Requires the edit fiscal_year permission. Use this when the batch.finished broadcast of a generation run was not received.

// HTTP 200 OK
{
    "sheetsUrl": "https://…/Kontoauszüge.zip?X-Amz-Expires=300&…"
}

Error responses

Fiscal year not found

// HTTP 404 Not Found
{
    "message": "No query results for model [Modules\\Accounting\\FiscalYear] {id}"
}

Unauthorized access

// HTTP 403 Forbidden
{
    "message": "This action is unauthorized."
}

Common use cases

Get current fiscal year

GET /fiscal_year?filter[open]=1&sort=-start_date&limit=1

This returns the most recent open fiscal year, which is likely the current one.

Get closed fiscal years for reporting

GET /fiscal_year?filter[closed]=1&sort=-closed_at

This returns all closed fiscal years, sorted by when they were closed (most recent first).

Get fiscal year with closing checklist

GET /fiscal_year/{id}?append=checklist

This includes the fiscal year closing checklist, useful for year-end procedures.

Read more about Pagination, Filtering, Sorting and Includes on the Introduction page.