---
title: "Read Facets"
method: GET
path: "/api/invoices/facets"
tags: ["invoices"]
---

# Read Facets

`GET /api/invoices/facets`

## Request

- Base URL: `https://demo.usesecuro.com` (the document declares no server; this is the origin it was published from)
- URL: `https://demo.usesecuro.com/api/invoices/facets`
- Auth: OAuth 2
  - Password
  - Token URL: `/api/auth/login`
- TypeScript: <https://skmtc.dev/usesecuro/apis/securo/docs/api/invoices/facets/get.ts> (a function with typed inputs; its response is checked against the schema)

Years that have invoices, and how many are in each state.

One call for the whole filter bar. The counts use the same derived
state the list does, so a chip reading 3 opens a list of exactly 3.

## Query parameters

- `year` integer, nullable
- `direction` 'receivable' | 'payable': Which side of the ledger to read

## Headers

- `X-Workspace-Id` string, nullable

## Response `200`

Successful Response

- InvoiceFacets: What the filter bar needs to render itself. `years` is every year that has an invoice, newest first, and is never narrowed by the `year` parameter — otherwise picking a year would remove every other year from the picker.
  - `years` integer[], required
  - `counts` InvoiceFacetCounts, required
    - `all` integer, required
    - `open` integer, required
    - `overdue` integer, required
    - `paid` integer, required
    - `draft` integer, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-05** `416a7752fec4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/usesecuro/apis/securo/changes/api/invoices/facets/get.md)

---

[API](https://skmtc.dev/usesecuro/apis/securo.md) - [All operations](https://skmtc.dev/usesecuro/apis/securo/llms.txt) - [OpenAPI document](https://skmtc.dev/usesecuro/apis/securo/revisions/416a7752fec4?raw)