Skip to main content
The Budgets API allows you to create, update, delete, and retrieve budget information for categories.

​
summary

Get a summary of all budgets with spending data. 
await client.budgets.summary()

​
Parameters

No parameters required.

​
Response

Returns an array of budget summaries with spending analytics.
​
budgets
array
Array of budget summary objects
Each budget summary includes:
​
id
string
Budget ID
​
amount
string
Budget amount
​
categoryId
string
Category ID
​
categoryName
string
Category name
​
categoryIcon
string
Category icon
​
parentCategoryId
string | null
Parent category ID if this is a subcategory
​
parentCategoryName
string | null
Parent category name
​
oneYearAverage
string
Average spending over the past year
​
last3MonthAverage
string
Average spending over the last 3 months
​
ytdSpend
string
Year-to-date spending
​
lastMonthSpend
string
Last month’s spending
​
thisMonthSpend
string
Current month’s spending
​
projectedSpend
string
Projected spending for the month
​
createdAt
Date
Budget creation timestamp
​
updatedAt
Date
Budget last update timestamp

​
details

Get detailed budget information including monthly averages. 
await client.budgets.details({
  id: "budget-id",
  fromDate: new Date("2024-01-01"),
  toDate: new Date("2024-12-31")
})

​
Parameters

​
id
string
required
Budget ID
​
fromDate
Date
required
Start date for the analysis period
​
toDate
Date
required
End date for the analysis period

​
Response

​
budgetSummary
object
Budget summary object (same structure as summary endpoint)
​
monthlyAverages
array
Array of monthly average spending data
Each monthly average object includes:
​
month
string
Month identifier (e.g., “2024-01”)
​
average
string
Average spending for that month

​
create

Create a new budget for a category. 
await client.budgets.create({
  categoryId: "category-id",
  amount: "500.00"
})

​
Parameters

​
categoryId
string
required
ID of the category to budget for
​
amount
string
required
Budget amount as a string numeric literal (e.g., “500.00”)

​
Response

​
id
string
Created budget ID
​
categoryId
string
Category ID
​
amount
string
Budget amount
​
createdAt
Date
Creation timestamp
​
updatedAt
Date
Last update timestamp

​
update

Update an existing budget. 
await client.budgets.update({
  id: "budget-id",
  categoryId: "category-id",
  amount: "600.00"
})

​
Parameters

​
id
string
required
Budget ID to update
​
categoryId
string
required
Category ID
​
amount
string
required
Updated budget amount

​
Response

Returns the updated budget object.

​
delete

Delete a budget. 
await client.budgets.delete({
  id: "budget-id"
})

​
Parameters

​
id
string
required
Budget ID to delete

​
Response

Returns the deleted budget object.

​
TypeScript Types

type Budget = {
  id: string
  categoryId: string
  userId: string
  amount: Intl.StringNumericLiteral
  createdAt: Date
  updatedAt: Date
}

type BudgetWithRelations = Pick<
  Budget,
  "id" | "amount" | "createdAt" | "updatedAt"
> & {
  categoryId: string
  categoryName: string
  categoryIcon: string
  parentCategoryId: string | null
  parentCategoryName: string | null
  parentCategoryIcon: string | null
}

type BudgetSummary = BudgetWithRelations & {
  oneYearAverage: Intl.StringNumericLiteral
  last3MonthAverage: Intl.StringNumericLiteral
  ytdSpend: Intl.StringNumericLiteral
  lastMonthSpend: Intl.StringNumericLiteral
  thisMonthSpend: Intl.StringNumericLiteral
  projectedSpend: Intl.StringNumericLiteral
}

type BudgetDetails = {
  budgetSummary: BudgetSummary
  monthlyAverages: {
    month: string
    average: Intl.StringNumericLiteral
  }[]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us