Skip to main content
The Categories API allows you to retrieve transaction categories for organizing income and expenses.

​
getAll

Retrieve all categories, optionally filtered by group and transaction type. 
await client.categories.getAll({
  groupId: "group-id",
  type: "EXPENSE"
})

​
Parameters

​
groupId
string
Optional group ID to filter categories
​
type
enum
Optional transaction type to filter by: INCOME, EXPENSE, or TRANSFER

​
Response

Returns an array of category objects.
​
id
string
Category ID
​
name
string
Category name
​
icon
string
Category icon identifier
​
type
enum
Transaction type: INCOME, EXPENSE, or TRANSFER
​
parentId
string | null
Parent category ID if this is a subcategory
​
groupId
string | null
Group ID if category is group-specific
​
userId
string | null
User ID if category is user-specific (custom category)
​
createdAt
Date
Creation timestamp
​
updatedAt
Date
Last update timestamp

​
getAllSubCategories

Retrieve all subcategories, optionally filtered by group and transaction type. 
await client.categories.getAllSubCategories({
  groupId: "group-id",
  type: "EXPENSE"
})

​
Parameters

​
groupId
string
Optional group ID to filter subcategories
​
type
enum
Optional transaction type to filter by: INCOME, EXPENSE, or TRANSFER

​
Response

Returns an array of subcategory objects (categories that have a non-null parentId). The structure is the same as the getAll endpoint response.

​
Category Hierarchy

Categories support a parent-child relationship:
  • Parent categories: Categories with parentId: null
  • Subcategories: Categories with a non-null parentId that references a parent category
Example hierarchy: 
Food (parent)
  ├─ Groceries (subcategory)
  ├─ Restaurants (subcategory)
  └─ Coffee (subcategory)

Transportation (parent)
  ├─ Gas (subcategory)
  └─ Public Transit (subcategory)

​
TypeScript Types

type TransactionType = "INCOME" | "EXPENSE" | "TRANSFER"

type Category = {
  id: string
  name: string
  icon: string
  type: TransactionType
  parentId: string | null
  groupId: string | null
  userId: string | null
  createdAt: Date
  updatedAt: Date
}

​
Constraints

  • Category name, type, group, and user combination must be unique
  • Categories can be:
    • System categories: Available to all users (userId: null, groupId: null)
    • Group categories: Shared within a group (groupId: set, userId: null)
    • User categories: Private to a specific user (userId: set)
  • Deleting a parent category cascades to all its subcategories

Build docs developers (and LLMs) love

Get started for freeTalk to us