Fiscal Year

• Introduction
  • Fiscal Year Types
• Allowed query parameters
• Retrieve a fiscal year
• List fiscal years
• 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
    }
}

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.