# Accounts
Source: https://docs.kualia.com/api/accounts
List, create, update, close, and delete bank accounts
Accounts hold transactions and balances. Accounts created through the API are always manual (unlinked) accounts; accounts connected to a bank feed appear with `"linked": true` and cannot be created or deleted via the API.
## The account object
```json theme={null}
{
"id": "k4859a...",
"name": "Chase Checking",
"type": "banking_checking",
"on_budget": true,
"balance": "1520.75",
"cleared_balance": "1480.75",
"pending_balance": "40.00",
"closed": false,
"notes": null,
"linked": false,
"last_reconciled_at": null,
"created_at": "2026-01-12T15:04:05.000Z",
"updated_at": "2026-07-01T09:30:00.000Z"
}
```
`on_budget` is `true` for banking and credit accounts (they participate in envelope budgeting) and `false` for investment and loan accounts.
## List accounts
```text theme={null}
GET /v1/workspaces/{workspace_id}/accounts
```
| Query parameter | Type | Description |
| ---------------- | ------- | ----------------------------------------- |
| `include_closed` | boolean | Include closed accounts. Default `false`. |
## Get an account
```text theme={null}
GET /v1/workspaces/{workspace_id}/accounts/{account_id}
```
## Create an account
```text theme={null}
POST /v1/workspaces/{workspace_id}/accounts
```
```bash theme={null}
curl -X POST https://api.kualia.com/v1/workspaces/WORKSPACE_ID/accounts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Emergency Fund",
"type": "banking_savings",
"initial_balance": "5000.00",
"initial_balance_date": "2026-07-01"
}'
```
| Field | Type | Required | Description |
| ---------------------- | ------ | -------- | -------------------------------------------------------------- |
| `name` | string | yes | Display name |
| `type` | string | yes | Account type (see below) |
| `initial_balance` | string | no | Starting balance as a decimal string |
| `initial_balance_date` | string | no | Date of the starting balance (`YYYY-MM-DD`, defaults to today) |
**Account types** — `banking_checking`, `banking_savings`, `banking_cash`, `banking_cash_management`, `banking_money_market`, `banking_cd`, `banking_other`, `credit_credit_card`, `credit_line_of_credit`, `credit_other`, `investment_brokerage`, `investment_401k`, `investment_ira`, `investment_roth_ira`, `investment_roth_401k`, `investment_hsa`, `investment_sep_ira`, `investment_simple_ira`, `investment_keogh`, `investment_529_plan`, `investment_403b`, `investment_other`, `loan_auto`, `loan_business`, `loan_commercial`, `loan_construction`, `loan_home_equity`, `loan_mortgage`, `loan_student`, `loan_other`.
## Update an account
```text theme={null}
PATCH /v1/workspaces/{workspace_id}/accounts/{account_id}
```
| Field | Type | Description |
| -------- | ------- | --------------------------------------------------------------------------------------------- |
| `name` | string | Rename the account |
| `notes` | string | Set the account notes |
| `closed` | boolean | `true` closes the account (reconciles its cleared transactions), `false` reopens a closed one |
## Delete an account
```text theme={null}
DELETE /v1/workspaces/{workspace_id}/accounts/{account_id}
```
Only accounts with no active transactions can be deleted — otherwise the request fails with `400`. Close the account instead if it has history you want to keep.
# Authentication
Source: https://docs.kualia.com/api/authentication
Create API keys and authenticate requests to the Kualia API
The API uses personal API keys as bearer tokens. Keys are tied to your Kualia account and can act on every workspace your account has access to (including family-shared workspaces).
## Creating a key
1. Open the web app and go to **Settings → API Keys**.
2. Click **Create Key**, give it a name, and optionally mark it **Read-only**.
3. Copy the key immediately — it is shown exactly once and never again. Kualia stores only a hash of it.
You can have up to 20 active keys. Use separate keys per integration so you can revoke one without breaking the others.
## Using a key
Send the key in the `Authorization` header of every request:
```bash theme={null}
curl https://api.kualia.com/v1/user \
-H "Authorization: Bearer kualia_a1b2c3d4..."
```
A missing or invalid key returns `401 unauthorized`.
## Scopes
| Scope | Granted by | Allows |
| ------- | ---------------------------------- | ------------------------------------------- |
| `read` | Every key | All `GET` endpoints |
| `write` | Keys created without **Read-only** | All `POST`, `PATCH`, and `DELETE` endpoints |
A read-only key calling a write endpoint gets `403 forbidden`.
## Revoking a key
In **Settings → API Keys**, click **Revoke** next to a key. Revocation is immediate and permanent — requests with that key start failing with `401` right away.
Treat API keys like passwords. Anyone who has a key can read and change your budget data. Never commit keys to source
control or share them in messages.
## Rate limits
Each key may make **200 requests per hour** (fixed window). Exceeding the limit returns `429 rate_limit_exceeded` with a `Retry-After` header (seconds until the window resets).
## Review status of API writes
Transactions created through the API land in the in-app **review queue** (`review_status: "needs_review"`) by default, so you can verify programmatic writes before treating them as final. Pass `"review_status": "reviewed"` on create if you want to skip the queue. Updates through the API never silently change a transaction's review status — it only changes when you send `review_status` explicitly.
# Categories
Source: https://docs.kualia.com/api/categories
Manage envelope categories and category groups
Categories are your budget envelopes, organized into category groups. System-managed items (like the Credit Card Payments group and its categories) are readable but cannot be modified through the API.
## List categories (grouped)
```text theme={null}
GET /v1/workspaces/{workspace_id}/categories
```
```json theme={null}
{
"data": {
"category_groups": [
{
"id": "k1180g...",
"name": "Essentials",
"type": "expense",
"system": false,
"categories": [
{
"id": "k5511c...",
"name": "Groceries",
"group_id": "k1180g...",
"archived": false,
"system": false,
"category_type": "custom"
}
]
}
]
}
}
```
For assigned/spent/available amounts per category, use the [months endpoints](/api/months).
## Get a category
```text theme={null}
GET /v1/workspaces/{workspace_id}/categories/{category_id}
```
## Create a category
```text theme={null}
POST /v1/workspaces/{workspace_id}/categories
```
```json theme={null}
{ "name": "Vacation", "group_id": "k1180g..." }
```
New categories are inserted at the top of their group.
## Update a category
```text theme={null}
PATCH /v1/workspaces/{workspace_id}/categories/{category_id}
```
| Field | Type | Description |
| ---------- | ------- | ----------------------------- |
| `name` | string | Rename the category |
| `group_id` | string | Move it to another group |
| `archived` | boolean | Archive (`true`) or unarchive |
## Delete a category
```text theme={null}
DELETE /v1/workspaces/{workspace_id}/categories/{category_id}
```
| Query parameter | Type | Description |
| --------------------- | ------ | --------------------------------------------------------- |
| `move_to_category_id` | string | Recategorize the category's transactions to this category |
Without `move_to_category_id`, affected transactions become uncategorized.
## Category groups
```text theme={null}
GET /v1/workspaces/{workspace_id}/category_groups
POST /v1/workspaces/{workspace_id}/category_groups
PATCH /v1/workspaces/{workspace_id}/category_groups/{group_id}
```
`POST` takes `{ "name": "..." }` and creates an expense group (duplicate names return `409`). `PATCH` takes `{ "name": "..." }` to rename. Groups cannot be deleted through the API; move or delete their categories first, then remove the group in the app.
# Errors
Source: https://docs.kualia.com/api/errors
Error response format, status codes, and rate limiting
Every error response has a non-2xx status code and a consistent body:
```json theme={null}
{
"error": {
"id": "404",
"name": "not_found",
"detail": "Transaction not found"
}
}
```
`id` mirrors the HTTP status, `name` is a stable machine-readable code, and `detail` is a human-readable explanation (its wording may change — branch on `name`, not `detail`).
## Error codes
| Status | `name` | When |
| ------ | --------------------- | ----------------------------------------------------------------------------------------- |
| 400 | `bad_request` | Invalid JSON, missing/invalid fields, malformed amounts or dates, invalid cursor |
| 401 | `unauthorized` | Missing, invalid, or revoked API key |
| 403 | `forbidden` | Read-only key on a write endpoint, no access to the workspace, or workspace archived |
| 404 | `not_found` | Unknown endpoint, or the workspace/account/transaction/merchant/category doesn't exist |
| 409 | `conflict` | Duplicate name (e.g. merchant or category group already exists) |
| 429 | `rate_limit_exceeded` | More than 200 requests in an hour for this key |
| 500 | `internal_error` | Something went wrong on our side — retry with backoff, and contact support if it persists |
## Rate limiting
Each API key may make **200 requests per hour**. When you exceed it, the response is `429` with a `Retry-After` header containing the number of seconds until the window resets:
```text theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 1284
{ "error": { "id": "429", "name": "rate_limit_exceeded", "detail": "Rate limit exceeded. The limit is 200 requests per hour per API key." } }
```
Batch endpoints help you stay under the limit — for example, [`POST /transactions`](/api/transactions) accepts up to 100 transactions in one request.
## Validation errors reference fields by path
Field errors name the offending field, including array indices, so you can pinpoint the bad row in a batch:
```json theme={null}
{
"error": {
"id": "400",
"name": "bad_request",
"detail": "transactions[2].amount must be a decimal string in the workspace currency (e.g. \"-12.34\")"
}
}
```
# Merchants
Source: https://docs.kualia.com/api/merchants
List, create, rename, and delete merchants (payees)
Merchants are the payees on your transactions. Kualia enriches many merchants automatically (logos, verified names); the API exposes the resolved display name.
## The merchant object
```json theme={null}
{
"id": "k9921m...",
"name": "Starbucks",
"created_at": "2026-02-03T10:00:00.000Z",
"updated_at": "2026-06-30T08:12:44.000Z"
}
```
## List merchants
```text theme={null}
GET /v1/workspaces/{workspace_id}/merchants
```
Returns all active merchants sorted by name.
## Get a merchant
```text theme={null}
GET /v1/workspaces/{workspace_id}/merchants/{merchant_id}
```
## Create a merchant
```text theme={null}
POST /v1/workspaces/{workspace_id}/merchants
```
```json theme={null}
{ "name": "Corner Bakery" }
```
Names are unique per workspace (case-insensitive); a duplicate returns `409 conflict`.
You usually don't need to create merchants explicitly — passing `merchant_name` when [creating a
transaction](/api/transactions) finds or creates the merchant in one step.
## Rename a merchant
```text theme={null}
PATCH /v1/workspaces/{workspace_id}/merchants/{merchant_id}
```
```json theme={null}
{ "name": "Corner Bakery Cafe" }
```
## Delete a merchant
```text theme={null}
DELETE /v1/workspaces/{workspace_id}/merchants/{merchant_id}
```
| Query parameter | Type | Description |
| --------------------- | ------ | ------------------------------------------------------------------------------ |
| `move_to_merchant_id` | string | Reassign the merchant's transactions and planned transactions to this merchant |
Without `move_to_merchant_id`, the merchant's transactions keep their data but lose the payee. The response reports what moved:
```json theme={null}
{
"data": {
"deleted": true,
"id": "k9921m...",
"moved_transaction_count": 42,
"updated_recurring_transaction_count": 1
}
}
```
# Budget Months
Source: https://docs.kualia.com/api/months
Read monthly envelope status and assign money to categories
Kualia is an envelope budget: each month you assign money to categories, spending draws it down, and leftovers carry forward. The months endpoints expose that monthly view and let you set assignments.
## Get a month
```text theme={null}
GET /v1/workspaces/{workspace_id}/months/{month}
```
`month` is `YYYY-MM`, e.g. `/months/2026-07`.
```json theme={null}
{
"data": {
"currency": "USD",
"month": {
"month": "2026-07",
"ready_to_assign": "412.50",
"summary": {
"percentage_funded": 82,
"total_target_amount": "3200.00",
"total_funded": "2624.00",
"total_remaining_to_fund": "576.00",
"total_overspent": "0.00"
},
"category_groups": [
{
"id": "k1180g...",
"name": "Essentials",
"type": "expense",
"categories": [
{
"id": "k5511c...",
"name": "Groceries",
"archived": false,
"category_type": "custom",
"assigned": "600.00",
"activity": "-484.20",
"carryover_from_previous": "13.75",
"available": "129.55",
"target": {
"assignment_needed": "600.00",
"remaining_to_assign": "0.00",
"underfunded_amount": "0.00",
"overfunded_by_amount": "0.00",
"funded_ratio": 1,
"snoozed": false
}
}
]
}
]
}
}
}
```
Per category: `assigned` is what you allocated this month, `activity` is the month's spending/inflows, `carryover_from_previous` is what rolled over, and `available` is what's left to spend. The `target` block reflects the category's savings/spending target for the month.
## Set a category's assigned amount
```text theme={null}
PATCH /v1/workspaces/{workspace_id}/months/{month}/categories/{category_id}
```
```bash theme={null}
curl -X PATCH https://api.kualia.com/v1/workspaces/WORKSPACE_ID/months/2026-07/categories/CATEGORY_ID \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "assigned": "650.00" }'
```
`assigned` **overwrites** the month's assignment — it is not an increment. To add \$50 to a category that already has
\$600 assigned, send `"assigned": "650.00"`. Negative values pull money back to Ready to Assign.
The response returns the category's refreshed month status (same shape as in `GET /months/{month}`), so you can see the new `available` immediately.
# API Overview
Source: https://docs.kualia.com/api/overview
Access your Kualia data programmatically with the public REST API
The Kualia API is a REST API that gives you full read and write access to your budget — transactions, accounts, merchants, categories, and monthly envelope assignments. Use it to build scripts, sync data into spreadsheets, or connect Kualia to your own tools.
**Base URL**
```text theme={null}
https://api.kualia.com/v1
```
## Quick start
**1. Create an API key.** In the web app, go to **Settings → API Keys** and click **Create Key**. Copy the key when it's shown — it's only displayed once.
**2. Find your workspace id.**
```bash theme={null}
curl https://api.kualia.com/v1/workspaces \
-H "Authorization: Bearer YOUR_API_KEY"
```
**3. Fetch your transactions.**
```bash theme={null}
curl "https://api.kualia.com/v1/workspaces/WORKSPACE_ID/transactions?since_date=2026-07-01" \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Response format
Every successful response wraps its payload in a `data` object:
```json theme={null}
{
"data": {
"currency": "USD",
"transactions": [
{
"id": "k1730s...",
"date": "2026-07-05",
"amount": "-12.34",
"account_id": "k4859a...",
"account_name": "Chase Checking",
"merchant_id": "k9921m...",
"merchant_name": "Starbucks",
"category_id": "k5511c...",
"category_name": "Dining Out",
"status": "cleared",
"review_status": "reviewed",
"type": "regular",
"notes": null,
"splits": null,
"deleted": false
}
],
"next_cursor": null
}
}
```
Errors return a matching `error` object — see [Errors](/api/errors).
## Conventions
| Convention | Detail |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Amounts | Decimal strings in the workspace currency, e.g. `"-12.34"`. Negative = money out, positive = money in. No milliunits, no cents-as-integers. |
| Dates | `YYYY-MM-DD` strings. Budget months are `YYYY-MM`. |
| Ids | Opaque strings returned by the API. Pass them back exactly as received. |
| Field case | All request and response fields are `snake_case`. |
| Writes | `POST` creates, `PATCH` partially updates (send only the fields you want to change), `DELETE` deletes. |
| Currency | Workspace-scoped responses include a top-level `currency` code so you always know what unit amounts are in. |
## Endpoints at a glance
| Resource | Operations |
| ---------------------------------------------------- | --------------------------------------------------------------------- |
| [`/user`](/api/workspaces) | Get the authenticated user |
| [`/workspaces`](/api/workspaces) | List and get workspaces |
| [`/workspaces/{id}/accounts`](/api/accounts) | List, get, create, update, close, delete accounts |
| [`/workspaces/{id}/transactions`](/api/transactions) | List, get, create (incl. transfers & splits), update, delete, restore |
| [`/workspaces/{id}/merchants`](/api/merchants) | List, get, create, rename, delete (with optional merge) |
| [`/workspaces/{id}/categories`](/api/categories) | List, get, create, update, archive, delete; manage groups |
| [`/workspaces/{id}/months/{month}`](/api/months) | Read a budget month; set assigned amounts per category |
Prefer talking to your budget from an AI assistant instead of code? Kualia also ships a hosted [MCP
server](/mcp/overview) with OAuth — no API keys needed.
# Transactions
Source: https://docs.kualia.com/api/transactions
List, create, update, delete, and restore transactions — including transfers and splits
## The transaction object
```json theme={null}
{
"id": "k1730s...",
"date": "2026-07-05",
"amount": "-84.20",
"account_id": "k4859a...",
"account_name": "Chase Checking",
"merchant_id": "k9921m...",
"merchant_name": "Costco",
"category_id": null,
"category_name": null,
"ready_to_assign": false,
"notes": "Weekly groceries + household",
"status": "cleared",
"review_status": "reviewed",
"type": "regular",
"transfer_account_id": null,
"splits": [
{
"amount": "-64.20",
"category_id": "k5511c...",
"category_name": "Groceries",
"ready_to_assign": false,
"notes": null
},
{
"amount": "-20.00",
"category_id": "k5512c...",
"category_name": "Household",
"ready_to_assign": false,
"notes": null
}
],
"deleted": false,
"created_at": "2026-07-05T18:22:10.000Z",
"updated_at": "2026-07-05T18:22:10.000Z"
}
```
* `amount` is the transaction total. Negative = money out, positive = money in.
* Single-category transactions have `category_id`/`category_name` set and `splits: null`. Split transactions have `splits` and a `null` top-level category.
* `ready_to_assign: true` marks income that flows straight to Ready to Assign instead of a category.
* `status` is `pending`, `cleared`, or `reconciled`. `review_status` is `reviewed` or `needs_review`.
* Transfers come in pairs: each side is a `type: "transfer"` transaction whose `transfer_account_id` points at the other account.
## List transactions
```text theme={null}
GET /v1/workspaces/{workspace_id}/transactions
```
| Query parameter | Type | Description |
| --------------- | ------ | ------------------------------------------------------ |
| `since_date` | date | Only transactions on or after this date (`YYYY-MM-DD`) |
| `until_date` | date | Only transactions on or before this date |
| `account_id` | string | Only transactions in this account |
| `category_id` | string | Only transactions with a split in this category |
| `status` | string | `pending`, `cleared`, or `reconciled` |
| `review_status` | string | `reviewed` or `needs_review` |
| `limit` | int | Page size, 1–500 (default 100) |
| `cursor` | string | Opaque pagination cursor from a previous response |
Results are ordered newest-first. The response includes `next_cursor`; pass it back as `cursor` to fetch the next page, and stop when it is `null`.
Pages can contain fewer than `limit` items even when more results remain — always follow `next_cursor` rather than
counting rows.
## Get a transaction
```text theme={null}
GET /v1/workspaces/{workspace_id}/transactions/{transaction_id}
```
Deleted transactions are returned with `"deleted": true`.
## Create transactions
```text theme={null}
POST /v1/workspaces/{workspace_id}/transactions
```
Send a single object under `transaction`, or up to 100 under `transactions`. The batch is atomic — if any row is invalid, nothing is created.
```bash theme={null}
curl -X POST https://api.kualia.com/v1/workspaces/WORKSPACE_ID/transactions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transaction": {
"account_id": "k4859a...",
"date": "2026-07-05",
"amount": "-12.34",
"merchant_name": "Starbucks",
"category_id": "k5511c..."
}
}'
```
| Field | Type | Description |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `account_id` | string | **Required.** Account to book the transaction in |
| `date` | date | **Required.** `YYYY-MM-DD` |
| `amount` | string | **Required** (unless `splits`). Signed decimal total |
| `category_id` | string | Category for the whole amount. Optional — see auto-categorization below |
| `ready_to_assign` | boolean | `true` books the amount as income to Ready to Assign (instead of a category) |
| `splits` | array | Split lines `{ amount, category_id?, ready_to_assign?, notes? }` — replaces `amount`/`category_id` |
| `merchant_id` | string | Existing merchant id |
| `merchant_name` | string | Merchant by name — matched case-insensitively or created if new |
| `notes` | string | Free-text memo |
| `status` | string | `pending` or `cleared` (default `cleared`) |
| `review_status` | string | `reviewed` or `needs_review` (default `needs_review`) |
**Auto-categorization.** If you omit `category_id` (and don't set `ready_to_assign` or `splits`) on a transaction that
has a merchant, Kualia categorizes it automatically — the same way imported and AI-chat transactions are handled: your
active rules, then your past categorizations for that merchant, learned merchant→category mappings, reviewed history,
and finally an AI prediction for merchants it hasn't seen before. Anything it can't confidently categorize is left
uncategorized. Auto-categorized rows still default to `needs_review` so you can confirm them in the app. Pass an
explicit `category_id` to skip this entirely.
### Transfers
Set `"type": "transfer"` to move money between two accounts. Both sides of the pair are created and returned.
```json theme={null}
{
"transaction": {
"type": "transfer",
"from_account_id": "k4859a...",
"to_account_id": "k7731b...",
"amount": "500.00",
"date": "2026-07-05"
}
}
```
`amount` must be positive for transfers. An optional `category_id` categorizes the outflow side (useful for credit-card payments).
## Update a transaction
```text theme={null}
PATCH /v1/workspaces/{workspace_id}/transactions/{transaction_id}
```
Send only the fields you want to change: `date`, `amount`, `category_id`, `ready_to_assign`, `splits`, `merchant_id` (or `merchant_name`), `notes` (string or `null`), `account_id`, `status`, `review_status`.
* Changing `amount` on a single-category transaction keeps its current category; changing `category_id` keeps the amount.
* To edit a split transaction's amounts or categories, send the full `splits` array.
* `review_status` never changes unless you send it explicitly.
## Delete & restore
```text theme={null}
DELETE /v1/workspaces/{workspace_id}/transactions/{transaction_id}
POST /v1/workspaces/{workspace_id}/transactions/{transaction_id}/restore
```
Deletes are soft: balances and category activity are rolled back, but the transaction can be restored. Deleting one side of a transfer deletes both sides.
# User & Workspaces
Source: https://docs.kualia.com/api/workspaces
Identify the caller and list the workspaces a key can act on
Every budget in Kualia lives in a **workspace**. Almost all endpoints are scoped to one: `/v1/workspaces/{workspace_id}/...`. Start here to find your workspace ids.
## Get the authenticated user
```text theme={null}
GET /v1/user
```
```bash theme={null}
curl https://api.kualia.com/v1/user \
-H "Authorization: Bearer YOUR_API_KEY"
```
```json theme={null}
{
"data": {
"user": {
"id": "user_2ab...",
"email": "you@example.com",
"name": "Igor",
"default_workspace_id": "k1234..."
}
}
}
```
## List workspaces
```text theme={null}
GET /v1/workspaces
```
```json theme={null}
{
"data": {
"workspaces": [
{
"id": "k1234...",
"name": "Family Budget",
"currency": "USD",
"timezone": "America/New_York",
"role": "admin",
"archived": false
}
]
}
}
```
`role` is `admin` for workspaces you own (or family groups you manage) and `member` otherwise.
## Get a workspace
```text theme={null}
GET /v1/workspaces/{workspace_id}
```
Returns the same fields plus `ready_to_assign` — the amount of money not yet assigned to any category:
```json theme={null}
{
"data": {
"workspace": {
"id": "k1234...",
"name": "Family Budget",
"currency": "USD",
"timezone": "America/New_York",
"role": "admin",
"archived": false,
"ready_to_assign": "412.50"
}
}
}
```
Archived workspaces are listed by `GET /v1/workspaces` but reject all other API calls with `403`.
# Envelope Budgeting
Source: https://docs.kualia.com/envelope-budgeting
Understand the budgeting method that powers Kualia
## What is Envelope Budgeting?
Envelope budgeting is a method where you divide your income into categories (envelopes) and allocate a specific amount to each one. When you spend money, it comes out of the relevant envelope. When an envelope is empty, you stop spending in that category or move money from another envelope.
## The Core Principles
### 1. Give Every Dollar a Job
When money comes in, you assign it to categories. Your **Ready to Assign** balance shows money that hasn't been assigned yet. The goal is to get this to zero - not by spending it, but by putting it into envelopes.
### 2. Embrace Your True Expenses
Some expenses don't happen monthly. Annual subscriptions, car insurance, holiday gifts - set up categories for these and fund them a little each month so you're ready when the bill comes.
### 3. Roll With the Punches
Overspent on dining out? Move money from another category to cover it. Your budget is a living plan, not a rigid set of rules.
### 4. Age Your Money
Over time, you'll start spending money you earned last month (or earlier) rather than money that just came in. This buffer means you're no longer living paycheck to paycheck.
## How It Works in Kualia
### Category Groups & Categories
Your budget is organized into **category groups** that contain individual **categories**:
| Category Group | Categories |
| -------------- | ----------------------------- |
| Housing | Rent, Utilities, Insurance |
| Food | Groceries, Dining Out |
| Transportation | Gas, Car Payment, Maintenance |
| Savings | Emergency Fund, Vacation |
### The Budget View
The budget view is where you manage your envelopes each month. For each category you'll see:
* **Assigned** - how much you've put into this envelope this month
* **Activity** - spending and income in this category
* **Available** - what's left to spend
### Ready to Assign
The **Ready to Assign** amount at the top of your budget represents unassigned money. This includes:
* Income that hasn't been assigned to categories
* Money moved back from categories
Your goal each month is to bring Ready to Assign to **\$0.00** by distributing it across your categories.
### Credit Card Handling
Kualia has special handling for credit cards. When you spend on a credit card:
1. The spending category's available balance decreases
2. The credit card payment category tracks what you owe
3. When you make a payment, it reduces the credit card balance
This means your budget always reflects reality - credit card spending reduces your envelope balances immediately, not when you pay the bill.
## Getting Started with Envelope Budgeting
Write down everything you spend money on. Group similar expenses together.
Set up category groups and categories in Kualia matching your expense list.
Look at your bank balance and assign it to your most important categories first.
Enter transactions or connect your bank. Watch your available balances change.
Move money between categories as real life happens. Refine your budget each month.
# Accounts
Source: https://docs.kualia.com/features/accounts
Manage all your financial accounts in one place
## Overview
Accounts in Kualia represent your real-world financial accounts. They track balances and hold your transactions.
## Account Types
Kualia supports a wide range of account types organized into four categories:
### Banking
| Type | Description |
| --------------- | -------------------------- |
| Checking | Everyday spending accounts |
| Savings | Savings accounts |
| Cash | Physical cash tracking |
| Cash Management | Cash management accounts |
| Money Market | Money market accounts |
| CD | Certificates of deposit |
### Credit
| Type | Description |
| -------------- | -------------------- |
| Credit Card | Credit card accounts |
| Line of Credit | Lines of credit |
### Investment
| Type | Description |
| -------------------- | ------------------------------ |
| Brokerage | Taxable investment accounts |
| 401(k) / 403(b) | Employer retirement accounts |
| IRA / Roth IRA | Individual retirement accounts |
| HSA | Health savings accounts |
| 529 Plan | Education savings |
| SEP IRA / SIMPLE IRA | Self-employment retirement |
### Loans
| Type | Description |
| --------------------- | ----------------------- |
| Mortgage | Home loans |
| Auto | Car loans |
| Student | Student loans |
| Home Equity | Home equity loans/lines |
| Business / Commercial | Business loans |
## Adding Accounts
### Manual Accounts
Create an account by specifying:
* Name
* Account type
* Starting balance
### Linked Accounts
[Connect your bank](/features/bank-connections) to automatically create accounts from your bank. Linked accounts sync balances and transactions automatically.
## Balance Tracking
Each account tracks three balance types:
* **Current Balance** - total balance including all transactions
* **Cleared Balance** - only cleared and reconciled transactions
* **Pending Balance** - only pending transactions
> Current Balance = Cleared Balance + Pending Balance
## Reconciliation
Reconcile your accounts against bank statements to ensure accuracy. When you reconcile:
1. Compare your Kualia cleared balance to your bank statement
2. Mark matching transactions as reconciled
3. Create a balance adjustment if there's a discrepancy
## Account Organization
Customize how accounts appear in your sidebar by reordering them within their groups.
## Closing Accounts
When you close a bank account or pay off a loan, you can mark the account as **closed**. Closed accounts:
* No longer appear in your active accounts list
* Retain all historical transaction data
* Can be reopened if needed
# AI Assistant
Source: https://docs.kualia.com/features/ai-assistant
Chat with Kualia to manage your budget, import statements, and answer questions about your money
## Overview
Kualia ships with a built-in AI assistant that has direct access to your real budget data. Open it from the chat icon in the sidebar and ask it anything from "how much did I spend on groceries last month?" to "import this credit card statement". It reads live data and can edit transactions, assign money, set goals, and more on your behalf.
The assistant is scoped to your active workspace, respects your permissions, and never sees data from workspaces you don't have access to.
## What you can ask it
### Look up transactions and accounts
* "Show me my last 20 transactions"
* "What did I spend at Amazon in April?"
* "List my accounts and their balances"
* "What subscriptions am I paying for right now?"
### Add, edit, and delete transactions
* "Add a \$42 grocery transaction at Trader Joe's yesterday from my Chase Checking"
* "Log a \$1,500 paycheck deposit today"
* "Recategorize the Costco charge from last Saturday as Household"
* "Mark all my pending Amazon transactions as reviewed"
* "Delete the duplicate Spotify charges from last week"
* "Restore the transactions I just deleted by mistake"
When the assistant references a specific transaction, it links directly to that transaction's page in the web app. Click through to open it.
### Import statements and receipts
Drag a file onto the chat. The assistant parses it and creates the transactions for you, so you don't need to retype rows.
| Supported | Notes |
| --------- | ----------------------------------------------- |
| **CSV** | Bank exports, exports from other budgeting apps |
| **PDF** | Bank and credit card statements |
| **Image** | Receipts (PNG, JPG) |
Examples:
* "Import this Amex PDF" *(attach the file)*
* "Categorize the rows in this CSV and add them to my Apple Card"
* "Here's a receipt for last night's dinner, split it across Eating Out and Drinks"
The assistant picks the destination account from the filename or statement header. For example, `amex_statement_2026-04.pdf` lands in your Amex account. Imported rows arrive as **Needs Review** and are auto-categorized when there's a confident match. Duplicates are detected against existing transactions on the same account and skipped; the assistant reports the count and asks before force-importing them.
File attachments are capped at 15 MB each. Larger statements should be split or trimmed first.
### Assign money to envelopes
* "Assign \$400 to Groceries this month"
* "Fund all my underfunded categories from Ready to Assign"
* "Move \$50 from Eating Out to Gas"
* "Pull \$200 out of Vacation back to Ready to Assign"
The assistant reads the current assignment before changing it, so relative moves like "add \$50" or "cover the overspending" update the right total instead of overwriting it.
### Manage categories and groups
* "Create a new category called Pet Care under Variable Expenses"
* "Rename Subscriptions to Recurring"
* "Move the Coffee category into Eating Out"
* "Archive my old Vacation 2024 category"
* "Sort my Variable Expenses alphabetically"
* "Create a new group called Annual Bills"
### Set funding targets and goals
* "Set Groceries to refill to \$600 every month"
* "Add a \$5,000 by December savings goal on Emergency Fund"
* "Maintain a \$1,000 balance in Car Repairs, \$50 a month"
* "Remove the target on Gifts"
The assistant handles every target type Kualia supports: recurring, rollover, maintain-balance, and one-time. See [Targets](/features/targets) for the underlying behavior.
### Reports and analysis
* "How much did I spend on dining out the last six months?"
* "What was my savings rate in Q1?"
* "Compare my income to spending for the year"
* "Which categories are over budget this month?"
* "Show me my account balance trend over the last year"
* "Roll up spending by category for the last 12 months"
These pull from the same pre-aggregated reports the in-app charts use, so the numbers match what you see on the [reports views](/platforms/web-app) exactly.
### File feature requests and bug reports
When you ask for something Kualia doesn't do yet, the assistant can file it on the public feedback site at [feedback.kualia.com](https://feedback.kualia.com) on your behalf, attributed to your account. It searches existing requests first to avoid duplicates. If it finds a close match, it tells you the current status (planned, in progress, shipped) and offers to upvote it.
* "I wish there was a dark mode for charts, file that for me"
* "There's a bug where the iOS widget shows stale balances overnight"
* "Take my vote off the request you filed yesterday"
Feedback posts are public. The assistant won't include your balances, transaction amounts, account names, or merchants
in the body. It only writes a generic description of the gap or bug.
## What it won't do
* **Move real money.** The assistant can record transfers between your accounts and adjust envelopes, but it doesn't initiate bank-side payments.
* **Connect new bank accounts.** Plaid linking still happens through the [bank connections](/features/bank-connections) flow.
* **Auto-approve imported transactions.** Rows it creates always land as **Needs Review** so you stay in control of categorization. Even when you ask it to update them later, they keep that status until you mark them reviewed yourself.
* **Give tax, legal, or investment advice.** It will redirect you to a qualified professional.
## Tips
Drag files straight into the chat input: CSVs, PDFs, and receipt images. No upload button needed.
Pin a workspace before chatting. The assistant defaults to your active workspace and won't ask which one you mean
unless you name a different one explicitly.
Short questions get short answers, and they run faster. Simple lookups route to a lighter model automatically;
multi-step edits and imports use the more capable one.
## Related
* [Importing data](/more/importing-data): manual import flows outside the chat.
* [Targets](/features/targets): how funding goals work in Kualia.
* [Transactions](/features/transactions): manual transaction entry, splits, and review states.
# Assigning Money
Source: https://docs.kualia.com/features/assigning-money
How to allocate your income to budget categories
## Overview
Assigning money is the core action in Kualia. When you receive income, it goes into your **Ready to Assign** balance. From there, you distribute it across your budget categories.
## How It Works
### Ready to Assign
Your Ready to Assign (RTA) balance is calculated as:
> **Ready to Assign** = Total Income - Total Assigned Across All Categories
When this number is positive, you have money waiting to be assigned. When it's zero, every dollar has a job. If it's negative, you've over-assigned - you've promised more money to categories than you actually have.
### Assigning to a Category
To assign money to a category:
1. Navigate to the **Budget** view
2. Select the month you want to budget for
3. Click on a category's **Assigned** column
4. Enter the amount you want to assign
5. The category's **Available** balance updates immediately
### Moving Money Between Categories
If you overspend in one category, you can move money from another:
1. Reduce the assigned amount in the source category
2. Increase the assigned amount in the destination category
Your total budget stays balanced - you're just reshuffling your envelopes.
## Monthly Assignments
Each category tracks its assigned amount **per month**. This means:
* January's assignments are separate from February's
* You can plan ahead by assigning money to future months
* Available balances roll over from month to month
## Tips
Use [targets](/features/targets) to automate your assignment goals. Kualia will tell you how much each category needs
based on your target settings.
Assign your most essential categories first (rent, utilities, groceries) before funding discretionary spending.
# Bank Connections
Source: https://docs.kualia.com/features/bank-connections
Connect your bank accounts for automatic transaction imports
## Overview
Kualia uses [Plaid](https://plaid.com) to securely connect to your bank and import transactions automatically. This eliminates manual data entry and keeps your budget up to date.
## Supported Countries
Kualia currently supports bank connections in:
* **United States** 🇺🇸
* **Canada** 🇨🇦
Support for additional countries may be added in the future.
## How It Works
### Connecting Your Bank
Go to Accounts and select "Connect Bank" (or "Link Account").
Plaid's secure interface lets you search for your financial institution.
Enter your bank credentials directly in Plaid's secure window. Kualia never sees your bank login credentials.
Choose which accounts to link - checking, savings, credit cards, etc.
Your accounts appear in Kualia and transactions start importing.
### What Gets Imported
When you connect your bank, Kualia imports:
* **Account balances** - updated regularly
* **Transactions** - new transactions are synced automatically
* **Institution details** - bank name and logo
### Transaction Sync
After the initial connection, Kualia receives webhook notifications from Plaid whenever new transactions are available. The sync process:
1. Plaid notifies Kualia of new data
2. Kualia fetches added, modified, and removed transactions
3. New transactions are imported and auto-categorized
4. Modified transactions are updated
5. Removed transactions are handled appropriately
## Smart Features
### Auto-Categorization
Imported transactions are automatically categorized based on:
* Your categorization history for the same merchant
* AI-powered merchant classification
* Merchant name matching
### Merchant Recognition
Kualia maintains a merchant database that:
* Cleans up raw bank descriptions into readable names
* Displays merchant logos when available
* Remembers your preferred category for each merchant
### Duplicate Detection
When you connect your bank, Kualia detects potential duplicates between:
* Manually entered transactions and imported ones
* Pending and posted versions of the same transaction
You can approve or reject suggested matches.
## Connection Health
Each bank connection has a health status:
| Status | Meaning |
| ---------------- | ----------------------------------------- |
| **Healthy** | Connection is working normally |
| **Error** | There's an issue that needs attention |
| **Pending** | Initial setup in progress |
| **Disconnected** | Connection lost, re-authentication needed |
If your connection shows an error, you may need to re-authenticate through Plaid. This can happen when your bank requires periodic re-verification.
## Security
* Kualia uses Plaid, a trusted financial data platform used by thousands of apps
* Your bank credentials are entered directly into Plaid's secure interface
* Kualia never stores your bank username or password
* Data is encrypted in transit and at rest
* You can disconnect your bank at any time
## Disconnecting
To disconnect a bank:
1. Go to your account settings
2. Find the bank connection
3. Select disconnect
Disconnecting stops future syncs but keeps your existing transaction history.
# Family Sharing
Source: https://docs.kualia.com/features/family-sharing
Share Kualia workspaces, budgets, and accounts with the people you budget with
## Overview
Family Sharing lets you budget with other people in one family group. After someone joins, family workspaces appear in their workspace switcher and stay in sync across web and iOS.
Use Family Sharing only with people you trust with your financial information. Everyone in the family can see shared family workspaces and the budget data inside them.
## Group Size
A family group has:
* **1 group manager** - the person who creates the family group
* **Up to 5 additional members** - people invited by the group manager
* **6 people total** - the manager plus five members
Pending invites reserve member slots until they are accepted, revoked, or expire.
## What Members Can See
When someone joins your family group, they can see family workspaces from other active members. This includes the financial data inside those workspaces:
* Budgets, category groups, categories, and assigned amounts
* Accounts and account balances
* Transactions, including imported and manually entered transactions
* Planned transactions, targets, and reports
* Bank connections that are available to the family workspace
Regular members can see joined family members. Only the group manager can see and manage pending invites.
## What Members Can Do
Family members can work in shared family workspaces. They can add and update day-to-day budget data such as transactions, accounts, categories, assignments, targets, and planned transactions.
Some actions are limited to the group manager or the workspace owner:
| Action | Group manager | Member |
| -------------------------------------------- | --------------------------------- | ------------------- |
| Invite new family members | Yes | No |
| Revoke pending invites | Yes | No |
| Remove joined members | Yes | No |
| Leave the family group | Yes, after removing other members | Yes |
| Manage workspace settings | Yes | Own workspaces only |
| Rename, archive, or delete shared workspaces | Yes | Own workspaces only |
| Manage their own bank connections | Yes | Yes |
Bank connections stay owned by the person who connected them. Active family members can use eligible linked accounts in family workspaces, but only the connection owner can reconnect or disconnect that bank connection.
## Invites
The group manager sends invites from **Settings > Family**. Invites are sent by email and expire after 14 days.
The person accepting the invite must sign in with the same email address that received it. A Kualia account can belong to one family group at a time. If someone already belongs to another family, they need to leave it before joining a new one.
## Leaving or Removing Members
Members can leave a family group from **Settings > Family**. The group manager can remove members or revoke pending invites.
When someone leaves or is removed:
* Their personal Kualia account stays intact
* Their own personal workspaces stay with them
* Shared family workspaces no longer appear in their account
* Bank account links that crossed between that member and the old family are unlinked
The group manager cannot leave while other members are still in the family group. Remove the other members first, then leave or delete the family group.
## Subscription Access
Family members can use Kualia through their own active subscription or through the group manager's active subscription. If the manager's subscription expires and a member does not have their own active subscription, that member cannot continue using the app until access is restored.
See [Subscription & Pricing](/more/subscription) for billing details.
# Planned Transactions
Source: https://docs.kualia.com/features/recurring-transactions
Schedule one-time and recurring transactions before they happen
## Overview
Planned transactions help you prepare for money that will move in the future, such as bills, paychecks, transfers, and one-time purchases.
They appear on the **Planned** page and above your transaction list until they are entered or skipped.
## How It Works
Create a transaction as usual, then choose its due date and how often it repeats.
* Choose a future date with no repeat to schedule it once.
* Choose a repeat option to make it recurring, such as weekly, monthly, or yearly.
* Choose whether Kualia should enter it automatically or leave it for you to enter manually.
Each plan includes the account, payee, category, amount, status, and optional notes or reminder.
## Automatic vs Manual Entry
| Entry Mode | What Happens on the Due Date |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| **Enter automatically** | Kualia adds the transaction to your transaction list. A recurring plan moves to its next due date. |
| **Enter manually** | The plan stays due or overdue until you enter it, link an existing transaction, or skip it. |
Automatic entry works well for accounts you manage manually. Manual entry can help prevent duplicates when a connected bank will import the real transaction.
You can also use **Enter now** before the due date. The transaction is added with today's date, and a recurring plan moves to its next occurrence.
## One-Time vs Recurring
| Schedule | How It Works |
| ------------- | -------------------------------------------------------------------- |
| **One-time** | Happens once on the selected date, then the plan is completed. |
| **Recurring** | Repeats on the schedule you choose and shows the next upcoming date. |
## Examples
* **Monthly rent** - repeat monthly and enter automatically on the first of each month.
* **Electric bill** - repeat monthly and enter manually after the final amount is known or imported from your bank.
* **Car registration** - schedule it once for the renewal date and add a reminder one week before.
* **Paycheck** - repeat every other week so upcoming income is visible ahead of time.
You can edit, pause, skip, or delete a planned transaction at any time. Transactions that were already entered stay in your transaction history.
# Targets
Source: https://docs.kualia.com/features/targets
Set funding goals for your budget categories
## Overview
Targets tell Kualia how much money a category needs and when. They help you know exactly how much to assign each month so you stay on track with your financial goals.
## Target Types
Kualia supports four types of targets:
### Recurring
A fixed amount needed every period (e.g., every month, every week).
**Use for:** Rent, utilities, subscriptions, groceries - any expense that repeats on a regular schedule.
* Set the amount and frequency
* Kualia shows how much to assign each period
* Resets each period
**Example:** \$1,200 for rent, due monthly on the 1st.
### Recurring with Rollover
Same as recurring, but unused funds carry over to the next period instead of resetting.
**Use for:** Categories where you want to accumulate unused money - dining out, entertainment, clothing.
* Surplus from one period carries into the next
* Under-spending builds up a buffer
* Over-spending borrows from next period's allocation
**Example:** \$200/month for dining out. If you only spend \$150, next month starts with \$50 already available.
### Maintain Balance
Build up to and maintain a specific balance in a category.
**Use for:** Savings goals, emergency funds, sinking funds for large purchases.
* Set a target balance and optional target date
* Kualia calculates the monthly contribution needed
* Once the target balance is reached, no more assignments needed
**Example:** Save \$5,000 for an emergency fund by December, contributing \~\$420/month.
### One-Time
A single funding goal with no recurrence.
**Use for:** One-off savings goals or planned purchases.
## Setting Up a Target
Navigate to the budget view and select the category you want to add a target to.
Toggle the target option on for that category.
Select from Recurring, Recurring with Rollover, Maintain Balance, or One-Time.
Set the amount, frequency, start date, and other options based on the target type.
## Target Frequency Options
For recurring and recurring with rollover targets:
| Frequency | Example |
| --------- | --------------------------------------------- |
| Daily | Every day, every 2 days, etc. |
| Weekly | Every week on Monday, every 2 weeks, etc. |
| Monthly | Every month on the 15th, every 3 months, etc. |
| Yearly | Once a year on a specific date |
You can set custom intervals (e.g., every 2 weeks, every 3 months) using the **frequency interval** setting.
## Target Status Indicators
Kualia shows visual indicators for each category's target status:
* **Underfunded** - category needs more money to meet its target
* **Funded** - category has exactly enough for its target
* **Overfunded** - category has more than the target requires
## Snoozing Targets
If you need to skip a target for a specific month (e.g., skipping a savings contribution during a tight month), you can **snooze** the target for that month. The target resumes automatically the following month.
# Transactions
Source: https://docs.kualia.com/features/transactions
Track and manage your income and expenses
## Overview
Transactions are the record of money moving in and out of your accounts. Every transaction in Kualia is categorized, helping you see exactly where your money goes.
## Transaction Types
| Type | Description |
| ---------------------- | --------------------------------------- |
| **Regular** | Standard income or expense transactions |
| **Transfer** | Money moving between your own accounts |
| **Starting Balance** | Initial balance when you add an account |
| **Balance Adjustment** | Manual corrections to account balances |
## Adding Transactions
### Manual Entry
Create transactions manually with:
* **Date** - when the transaction occurred
* **Account** - which account the money came from or went to
* **Payee (Merchant)** - who you paid or received money from
* **Category** - which envelope to debit or credit
* **Amount** - how much
* **Notes** - optional details
* **Status** - pending or cleared
### Automatic Import
When you [connect your bank](/features/bank-connections), transactions are imported automatically. Imported transactions include:
* Smart merchant matching with logo display
* AI-powered auto-categorization based on your history
* Duplicate detection to avoid double-counting with manual entries
### Review Status
Imported transactions start as **Needs Review**. This lets you:
* Verify the category is correct
* Split transactions across multiple categories
* Confirm the amount and payee
Once reviewed, mark them as **Reviewed** to keep your budget clean.
## Split Transactions
A single transaction can be split across multiple categories. For example, a grocery store purchase might include:
* \$80 to Groceries
* \$15 to Household Items
* \$5 to Pet Supplies
Each split (called a **movement**) has its own category and amount.
## Transfers
When money moves between your own accounts, use a **transfer** transaction. Kualia links both sides automatically so:
* Your total net worth stays accurate
* Category balances aren't affected (unless it's a credit card payment)
## Search & Filtering
Search across all your transactions by payee, category, amount, or notes. Filter by:
* Account
* Category
* Date range
* Status (pending/cleared/reconciled)
* Review status
* Uncategorized transactions
# Connecting Your Bank
Source: https://docs.kualia.com/guides/connecting-your-bank
Step-by-step guide to linking your bank accounts
## Overview
This guide walks you through connecting your bank accounts to Kualia using Plaid. For details on how syncing, auto-categorization, and connection health work, see [Bank Connections](/features/bank-connections).
## Before You Start
* Make sure you have your bank login credentials ready
* Kualia supports banks in the **United States** and **Canada**
* Your bank credentials are entered directly into Plaid's secure window - Kualia never sees them
## Where to Start a Connection
You can start a bank connection from a few different places, depending on which app you're using.
### On iOS
* **Accounts tab** — tap to add a new account and choose **Connect bank**.
* **Side drawer** — open the side panel and select **Institutions** to add a new connection or manage existing ones.
### On Web
* **Accounts tab** — create a new account and choose to link a bank or create a manual account.
* **Settings** — open settings and select **Bank connections** in the side panel to add or manage connections.
## Connecting
## After Connecting
## Troubleshooting
# Getting Started Guide
Source: https://docs.kualia.com/guides/getting-started
A complete walkthrough for new Kualia users
## Welcome to Kualia
This guide walks you through everything you need to get started with Kualia and envelope budgeting.
## Step 1: Create Your Account
Sign up at [app.kualia.com](https://app.kualia.com) or download the iOS app. You can sign up with:
* **Email** - receive a one-time passcode
* **Google** - sign in with your Google account
## Step 2: Set Up Your Workspace
Your workspace is your budgeting environment. After signing up, you'll create one with a name that makes sense for you (e.g., "Personal Budget", "Family Finances").
## Step 3: Configure Your Budget
1. **Review default categories** - Kualia creates starter categories for you
2. **Customize category groups** - add, rename, or remove groups to match your life
3. **Add categories** - create categories for each expense type
4. **Set your income** - tell Kualia your expected monthly income
## Step 4: Add Your Accounts
Add all your financial accounts:
1. **Connect your bank** for automatic imports (US/Canada)
2. **Add manual accounts** for banks without Plaid support or cash accounts
3. **Set starting balances** for each account
## Step 5: Assign Your Money
Now comes the core of envelope budgeting:
1. Look at your **Ready to Assign** balance
2. Start assigning money to your most important categories first
3. Work your way down until Ready to Assign is \$0
## Step 6: Set Targets
Add [targets](/features/targets) to your categories so Kualia knows how much each one needs:
* Monthly bills → **Recurring** targets
* Flexible spending → **Recurring with Rollover** targets
* Savings goals → **Maintain Balance** targets
## Step 7: Plan Upcoming Transactions
Create [planned transactions](/features/recurring-transactions) for future bills, income, or transfers. Plans can happen once or repeat on a schedule, and Kualia can enter them automatically or leave them for you to enter manually.
## Next Steps
Deep dive into budget configuration.
Step-by-step bank connection guide.
# Setting Up Your Budget
Source: https://docs.kualia.com/guides/setting-up-your-budget
How to configure categories, targets, and assignments
## Overview
This guide walks you through setting up a complete budget in Kualia, from creating categories to assigning every dollar.
## Planning Your Categories
Before diving in, think about how you spend money. Common category groups include:
* **Fixed Expenses** - rent/mortgage, insurance, loan payments
* **Variable Expenses** - groceries, gas, dining out
* **Savings & Goals** - emergency fund, vacation, large purchases
* **Subscriptions** - streaming, gym, software
* **Personal** - clothing, hobbies, gifts
## Setting Up Targets
Once your categories exist, add targets so Kualia can guide your assignments each month. A target tells Kualia how much money a category needs and when, so you know exactly how much to assign.
Kualia supports four target types:
* **Recurring** — a fixed amount needed every period. Best for rent, utilities, subscriptions, and groceries.
* **Recurring with Rollover** — same as recurring, but unused funds carry over to the next period. Best for dining out, entertainment, or clothing where surplus should accumulate.
* **Maintain Balance** — build up to and hold a specific balance. Best for emergency funds, sinking funds, and savings goals.
* **One-Time** — a single funding goal with no recurrence. Best for a one-off purchase or savings goal.
To add a target, select a category from the budget view, toggle the target option on, choose the type, and configure the amount, frequency, and dates.
For full details on each type, frequency options, and status indicators, see [Targets](/features/targets).
## Your First Month
# Welcome to Kualia
Source: https://docs.kualia.com/introduction
Take control of your finances with envelope budgeting
These docs are a work in progress. Some pages may be incomplete or missing. We're actively updating them.
## What is Kualia?
Kualia is a personal finance application built around the **envelope budgeting** method. It helps you assign every dollar a job, track your spending, and stay on top of your financial goals.
### Key Features
Assign money to categories and know exactly where every dollar goes.
Automatically import transactions from US and Canadian banks via Plaid.
Share family workspaces, budgets, accounts, and transactions with the people you budget with.
Set spending targets and savings goals to stay on track.
Schedule one-time and recurring transactions before they happen.
Available on web and iOS with real-time sync across all devices.
Glance at your budget from your home screen.
## Get Started
Sign up at [app.kualia.com](https://app.kualia.com) or download the iOS app.
Create category groups and categories that match your spending habits.
Link your bank accounts for automatic transaction imports.
Give every dollar a job by assigning money to your categories.
# ChatGPT
Source: https://docs.kualia.com/mcp/chatgpt
Connect Kualia to ChatGPT as a custom connector
![ChatGPT]()
ChatGPT supports remote MCP servers as **custom connectors** on ChatGPT Plus, Pro, Business, Enterprise, and Edu plans.
Custom MCP connectors require Developer Mode (or a Business/Enterprise admin enabling them). On personal plans, enable
it in **Settings → Connectors → Advanced → Developer mode**.
## Add the connector
In ChatGPT, go to **Settings → Connectors**.
Click **Create** (or **Add custom connector**) and fill in:
* **Name**: `Kualia`
* **MCP server URL**: `https://api.kualia.com/mcp`
* **Authentication**: **OAuth**
Save, then click **Connect**. Your browser opens [app.kualia.com](https://app.kualia.com) for consent.
Start a new chat, click the **+** menu, choose **Use connectors**, and enable **Kualia**. ChatGPT can now query your budget.
## Try it
* "How much have I spent on subscriptions this year?"
* "What planned transactions are due in the next 7 days?"
* "Summarize my Q1 income."
## Disconnect
Remove from **Settings → Connectors**.
# Claude (web & desktop)
Source: https://docs.kualia.com/mcp/claude
Connect Kualia to Claude.ai or the Claude desktop app
![Claude]()
Connect Kualia to Claude on the web ([claude.ai](https://claude.ai)) or the desktop app so you can ask Claude about your budget, spending, and accounts in any conversation.
Connectors are available on Claude paid plans. The remote MCP connector flow is the same on web and desktop.
## Add the connector
In Claude, open **Settings → Connectors** (or **Settings → Integrations**, depending on your plan).
Click **Add custom connector** and enter:
* **Name**: `Kualia`
* **URL**: `https://api.kualia.com/mcp`
Save.
Find Kualia in your connectors list and click **Connect**. Your browser will open the Kualia app — sign in if you aren't already, then approve access.
Start a new chat, open the connectors menu, and toggle **Kualia** on. Claude will now have access to your budget data for that conversation.
## Try it
Ask Claude something like:
* "How much did I spend on groceries last month?"
* "Which envelopes are overspent right now?"
* "Summarize my income for Q1."
* "Move \$50 from Dining Out to Groceries for this month."
## Disconnect
Open **Settings → Connectors**, find Kualia, and click **Disconnect**.
# Claude Code
Source: https://docs.kualia.com/mcp/claude-code
Connect Kualia to Claude Code, the CLI and IDE coding assistant
![Claude Code]()
[Claude Code](https://claude.com/claude-code) can use Kualia as an MCP server so you can ask it to query your budget while you're in the terminal or your IDE.
## Add the connector
The fastest way is the `claude mcp add` command:
```bash theme={null}
claude mcp add --transport http kualia https://api.kualia.com/mcp
```
That registers Kualia as an HTTP MCP server in your user-level config.
Alternatively, use the in-app UI:
In Claude Code, run `/mcp` (or open **Settings → Connectors** in the desktop app).
Choose **Add server**, set the transport to **HTTP**, and enter:
* **Name**: `kualia`
* **URL**: `https://api.kualia.com/mcp`
Run `/mcp` again and select **Kualia → Connect**. Your browser opens the Kualia app for OAuth consent. Once you approve, the token is stored locally.
## Scope: user, project, or local
When adding the server you can pick a scope:
* **User** (default for the command above): available in every project on this machine.
* **Project**: writes to `.mcp.json` in the repo so collaborators can use it too. Add `--scope project`.
* **Local**: only this machine, this project. Add `--scope local`.
```bash theme={null}
claude mcp add --transport http --scope project kualia https://api.kualia.com/mcp
```
## Try it
```text theme={null}
> what categories am i overspending in this month?
> list my last 20 transactions tagged "subscriptions"
> assign $200 to Groceries for May
```
## Manage and disconnect
* `claude mcp list` — show configured servers
* `claude mcp remove kualia` — remove the server
* Inside a session, `/mcp` shows status and lets you reconnect or sign out.
# Claude Cowork
Source: https://docs.kualia.com/mcp/cowork
Connect Kualia to Claude Cowork as a personal connector
![Claude Cowork]()
[Claude Cowork](https://claude.com/cowork) lets teams share Claude with installed plugins and connectors. You can add Kualia as a personal connector so it's available in your Cowork chats without exposing it to the rest of your team.
## Add the connector
In Cowork, open **Settings → Connectors → Personal connectors**.
Click **Add custom connector** and enter:
* **Name**: `Kualia`
* **URL**: `https://api.kualia.com/mcp`
Click **Connect**. Your browser opens [app.kualia.com](https://app.kualia.com) for OAuth consent.
Open a Cowork chat, toggle the Kualia connector on, and ask away.
Personal connectors are scoped to your user account. Other Cowork members won't see your Kualia data unless they add
the connector and authorize their own Kualia account.
## Disconnect
Remove the connector from **Settings → Connectors**.
# Cursor
Source: https://docs.kualia.com/mcp/cursor
Connect Kualia to Cursor
![Cursor]()
[Cursor](https://cursor.com) supports remote MCP servers via its built-in MCP client.
## One-click install
If you're on a recent Cursor build, open **Settings → MCP** and click **Add new MCP server**, then choose **HTTP** as the transport.
## Manual install
Edit your Cursor MCP config:
* **macOS / Linux**: `~/.cursor/mcp.json`
* **Windows**: `%USERPROFILE%\.cursor\mcp.json`
Add Kualia under `mcpServers`:
```json theme={null}
{
"mcpServers": {
"kualia": {
"url": "https://api.kualia.com/mcp"
}
}
}
```
Save, then restart Cursor.
## Authorize
Open **Settings → MCP**. Kualia will show as **Needs authentication**. Click **Connect** — your browser opens [app.kualia.com](https://app.kualia.com) for OAuth consent. After approving, the green status dot indicates Kualia is ready.
## Use it
In Cursor's chat or composer, just ask:
* "Show me my biggest expenses last week."
* "What's left in my Eating Out envelope?"
Cursor will call the Kualia MCP tools automatically.
## Project-scoped install
To share with collaborators, commit a `.cursor/mcp.json` to the repo root with the same structure. Each teammate authorizes their own Kualia account on first use.
# Other clients
Source: https://docs.kualia.com/mcp/other-clients
Connect Kualia to VS Code, Windsurf, Zed, Continue, and any MCP-compatible client
Any client that speaks the [Model Context Protocol](https://modelcontextprotocol.io) over HTTP can connect to Kualia. The server URL is always:
```
https://api.kualia.com/mcp
```
OAuth is fully automatic — clients discover the auth endpoints from the server, register dynamically, and walk you through consent in your browser.
## VS Code (GitHub Copilot Chat)
VS Code supports MCP servers in agent mode. Add Kualia to your user `settings.json`:
```json theme={null}
{
"mcp": {
"servers": {
"kualia": {
"type": "http",
"url": "https://api.kualia.com/mcp"
}
}
}
}
```
Reload VS Code, open Copilot Chat in **Agent** mode, and approve the OAuth prompt that appears.
## Windsurf
In Windsurf, open **Settings → Cascade → MCP servers → Add server** and enter the Kualia URL with HTTP transport. Or edit `~/.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"kualia": {
"serverUrl": "https://api.kualia.com/mcp"
}
}
}
```
## Zed
In Zed, open the assistant panel settings and add a context server. In `settings.json`:
```json theme={null}
{
"context_servers": {
"kualia": {
"source": "custom",
"url": "https://api.kualia.com/mcp"
}
}
}
```
## Continue
Add Kualia to your `~/.continue/config.json`:
```json theme={null}
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "http",
"url": "https://api.kualia.com/mcp"
}
}
]
}
}
```
## Cline / Roo Code
Open the MCP server settings panel and add a remote server with URL `https://api.kualia.com/mcp` and transport **HTTP** (or **streamable HTTP**).
## Build your own client
Kualia implements the standard MCP authorization flow:
1. Unauthenticated request to `https://api.kualia.com/mcp` returns `401` with a `WWW-Authenticate` header pointing at `/.well-known/oauth-protected-resource`.
2. That document points at the authorization server's metadata at `/.well-known/oauth-authorization-server`.
3. Clients use Dynamic Client Registration (RFC 7591) and Authorization Code + PKCE to obtain a token.
4. Tokens are sent as `Authorization: Bearer ` on subsequent MCP requests.
Any spec-compliant MCP client library will handle all of this for you.
# MCP Overview
Source: https://docs.kualia.com/mcp/overview
Connect AI assistants to your Kualia data with the Model Context Protocol
## What is the Kualia MCP server?
Kualia exposes a remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so AI assistants like ChatGPT, Claude, Cursor, and Perplexity can read your budget data and help you reason about your finances directly, with your permission, and without copy-pasting.
**Server URL**
```
https://api.kualia.com/mcp
```
That single URL is everything you need. Paste it into any MCP-compatible client and the rest of the setup is automatic.
## What can the AI do?
Once connected, the assistant can read your transactions and balances, manage envelopes and targets, create and edit transactions in bulk, import statements you paste in, and generate spending and income reports. Everything is scoped to the workspaces your account has access to.
See the [full tool reference](/mcp/tools) for every available action, with parameters and batch limits.
## How authentication works
You never paste an API key. The connection uses OAuth 2.1 with PKCE and dynamic client registration, all driven by the MCP spec:
1. The client connects to `https://api.kualia.com/mcp`.
2. Kualia responds with a `WWW-Authenticate` header pointing to its OAuth metadata.
3. The client opens the Kualia app in your browser to ask for consent.
4. You approve, and the client receives a token scoped to your account.
5. The token is stored locally by the client and used for all future calls.
The first time you connect, you'll see a **Connect** or **Authorize** button. Clicking it opens [app.kualia.com](https://app.kualia.com) where you grant access.
## Pick your client
![ChatGPT]()
![Claude]()
![Claude Code]()
![Claude Cowork]()
![Cursor]()
![Perplexity]()
## Privacy
* Kualia only returns data for workspaces your account has access to.
* Tokens are stored by the client (e.g. on your laptop), not by the assistant provider.
* To disconnect, remove the connector from your AI client's settings.
# Perplexity
Source: https://docs.kualia.com/mcp/perplexity
Connect Kualia to Perplexity
![Perplexity]()
Perplexity supports remote MCP servers as **connectors** on paid plans.
## Add the connector
In Perplexity, go to **Settings → Connectors**.
Click **Add connector → Custom MCP server** and enter:
* **Name**: `Kualia`
* **URL**: `https://api.kualia.com/mcp`
Click **Connect**. Your browser opens the Kualia app for OAuth consent. Approve to finish setup.
In a Perplexity thread, open the connectors menu and enable **Kualia** for that thread.
## Try it
* "Compare my spending this month vs. last month."
* "What's my available balance across all checking accounts?"
## Disconnect
Remove from **Settings → Connectors**.
# MCP Tool Reference
Source: https://docs.kualia.com/mcp/tools
Every tool exposed by the Kualia MCP server, grouped by category
These are the tools your MCP client can call once you've connected to `https://api.kualia.com/mcp`. Names and parameters match exactly what the server registers. The same catalog powers the in-app [AI Assistant](/features/ai-assistant).
See [MCP overview](/mcp/overview) for how to connect, and the per-client guides ([ChatGPT](/mcp/chatgpt), [Claude](/mcp/claude), [Claude Code](/mcp/claude-code), [Cursor](/mcp/cursor), [Perplexity](/mcp/perplexity)) for client-specific setup.
## Workspaces & accounts
| Tool | What it does | Key params |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `kualia_list_workspaces` | Lists the workspaces the authenticated user can access. Call this only when switching workspaces explicitly. | *none* |
| `kualia_export_workspace_data` | Creates a ZIP archive with CSV files for categories and targets, monthly plan data, bank accounts, and transactions. Credit-card categories use their bank account name, plan rows are ordered by `year_month`, and Ready-to-Assign movements use `Ready to Assign` as their category name. Returns a download URL that expires after 24 hours. Split transactions use one row per movement, linked by `transaction_id`, `movement_index`, and `movement_count`. | `workspaceId?` |
| `kualia_list_bank_accounts` | Lists every bank account with name, type, on-budget flag, currency, current balance, and closed flag. | `workspaceId?`, `includeClosed?` |
| `kualia_create_bank_account` | Creates a manual (unlinked) account from a `name` and `accountType`. `banking_*`/`credit_*` are on-budget; `investment_*`/`loan_*` are off-budget. Optionally seeds an opening balance. | `name` *(required)*, `accountType` *(required)*, `initialBalance?` + `initialBalanceDate?`, `workspaceId?` |
| `kualia_close_bank_account` | Closes an account non-destructively: reconciles it, marks it closed, disconnects any link, and keeps all transactions for history. Use instead of delete when the account has activity. | `bankAccountId` *(required)*, `workspaceId?` |
| `kualia_delete_bank_account` | Deletes an account. Only succeeds when the account has no transactions; otherwise it refuses and you should close it instead. Also removes a credit account's linked category. | `bankAccountId` *(required)*, `workspaceId?` |
## Transactions
| Tool | What it does | Key params |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `kualia_list_transactions` | Lists transactions for a single month, with splits expanded to one row per movement. Each row carries a `url` linking to the transaction in the web app. | `yearMonth` *(required)*, `workspaceId?`, `accountId?`, `categoryId?`, `type?`, `limit?` (default 500, max 1000) |
| `kualia_create_transactions` | Batch-creates regular or transfer rows (mix freely). Regular rows can be categorized, uncategorized, or sent directly to Ready to Assign. They are deduped against existing transactions on the same account and land as **Needs Review**. Up to 200 per call. | `transactions[]` *(required)*, `bankAccountId?`, `forceInsert?`, `workspaceId?` |
| `kualia_update_transactions` | Batch-updates existing transactions: date, amount, category, movements, merchant, notes, account, status, review status, even type conversion. Up to 200 per call. | `updates[]` *(required)*, `workspaceId?` |
| `kualia_delete_transactions` | Soft-deletes by id, reversing balance and budget side effects. Transfer pairs are deleted together. Up to 200 per call. | `transactionIds[]` *(required)*, `workspaceId?` |
| `kualia_restore_transactions` | Undeletes soft-deleted transactions, re-applying balance and budget side effects. Transfer pairs are restored together. Up to 200 per call. | `transactionIds[]` *(required)*, `workspaceId?` |
| `kualia_list_recurring_transactions` | Lists subscription, bill, and recurring-income templates with merchant, expected amount, and calculated next due date. | `status?` (`active` \| `inactive`, default `active`), `workspaceId?` |
### Creating transactions
For a regular, single-movement transaction, pass `amount` and choose one of:
* `categoryId` to categorize it.
* `readyToAssign: true` to treat it as income for Ready to Assign. This creates a movement with no category.
* Neither field to leave it uncategorized or let Kualia apply rules and suggestions.
```json theme={null}
{
"bankAccountId": "bank_account_checking",
"transactions": [
{
"merchantName": "Payroll",
"amount": "1200.00",
"date": "2026-06-15",
"readyToAssign": true,
"notes": "June paycheck"
}
]
}
```
Do not combine `readyToAssign: true` with `categoryId` on the same transaction or movement. For split transactions, pass
`movements` and put `readyToAssign: true` on the specific movement that should go to Ready to Assign.
## Categories & groups
| Tool | What it does | Key params |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `kualia_list_category_groups` | Lists category groups with their nested categories. | `workspaceId?` |
| `kualia_create_categories` | Batch-creates categories inside an existing group. Up to 50 per call. Per-row failures (duplicate names, unknown group) don't abort the batch. | `categories[]` *(required, with `name` + `categoryGroupId`)*, `workspaceId?` |
| `kualia_update_categories` | Batch-updates category `name`, `categoryGroupId`, or `iconName`. Up to 50 per call. | `updates[]` *(required, with `categoryId`)*, `workspaceId?` |
| `kualia_archive_categories` | Archive (`isArchived: true`) or unarchive (`false`) categories in bulk. System and credit-card categories are rejected. All-or-nothing per call. Up to 50. | `categoryIds[]` *(required)*, `isArchived` *(required)*, `workspaceId?` |
| `kualia_reorder_categories` | Custom rearrangement. Places categories at exact top-to-bottom positions, including cross-group moves. Use only for arbitrary orderings. | `groups[]` *(required, with `categoryGroupId` + `orderedCategoryIds`)*, `workspaceId?` |
| `kualia_sort_categories` | Server-side sort by `name_asc`/`name_desc`, `target_due_date_asc`/`_desc`, or `created_asc`/`_desc`. Sorts one group or every group. | `sortBy` *(required)*, `categoryGroupId?`, `workspaceId?` |
| `kualia_create_category_groups` | Batch-creates groups (`type: 'expense'`). Up to 10 per call. | `groups[]` *(required, with `name` + `type`)*, `workspaceId?` |
| `kualia_update_category_groups` | Batch-updates group `name` (and `type` back to `expense` if needed). Credit-card groups cannot be converted. Up to 10 per call. | `updates[]` *(required, with `categoryGroupId`)*, `workspaceId?` |
| `kualia_archive_category_groups` | Archive (soft-delete) or restore groups in bulk. Group must be empty to archive. Credit-card groups can't be archived. Up to 10 per call. | `categoryGroupIds[]` *(required)*, `isArchived` *(required)*, `workspaceId?` |
| `kualia_reorder_category_groups` | Custom rearrangement. Sets the top-to-bottom order of groups in the workspace. | `orderedCategoryGroupIds[]` *(required)*, `workspaceId?` |
| `kualia_sort_category_groups` | Server-side sort by `name_asc`/`name_desc` or `created_asc`/`created_desc`. | `sortBy` *(required)*, `workspaceId?` |
## Budgets & targets
| Tool | What it does | Key params |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kualia_set_category_assigned_amount` | Sets the **absolute** assigned amount for one category-month (single mode) or many (bulk mode). Overwrites the existing assignment; it's not a delta. Positive funds the category, negative pulls money back to Ready to Assign. | Single: `categoryId` + `yearMonth` + `assignedAmount`. Bulk: `updates[]`. Plus `workspaceId?`. |
| `kualia_get_envelope_month_status` | Returns one month of envelope status (assigned, activity, available) with assignment guidance (`remainingToAssign`, `underfundedAmount`, `assignmentNeeded`). Filter to a single category or group by id or name. | `yearMonth` *(required)*, `currentDate` *(required, YYYY-MM-DD)*, `categoryId?` \| `categoryName?` \| `groupId?` \| `groupName?`, `workspaceId?` |
| `kualia_list_category_targets` | Lists every category's target definition (type, amount, frequency, due date, etc.) for categories that have targets enabled. | `workspaceId?` |
| `kualia_create_category_target` | Creates a target on a category that doesn't have one. Types: `recurring`, `recurring_rollover`, `maintain_balance`, `one_time`. Credit-card categories are rejected. | `categoryId`, `targetType`, `amount` *(all required)*; plus `frequency?`, `frequencyInterval?`, `dayOfWeek?`, `dueDay?`, `firstDueDate?`, `targetDate?`, `monthlyContribution?`, `targetBalance?`, `workspaceId?` |
| `kualia_update_category_target` | Updates an existing target. Nullable fields accept `null` to clear (`monthlyContribution`, `targetBalance`, `targetDate`, `dayOfWeek`, `dueDay`). | `categoryId` *(required)*; same target fields as `create_category_target`, all optional; plus `workspaceId?` |
| `kualia_delete_category_target` | Disables the target on a category. Preserves the underlying settings so it can be re-enabled later. Idempotent. | `categoryId` *(required)*, `workspaceId?` |
## Reports
| Tool | What it does | Key params |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `kualia_get_monthly_summary` | The canonical "how much did I spend, save, or earn" report. Per-month `income`, `spending`, `savings`, `savingsRate`, plus `byCategory` and `byGroup` spending breakdowns. Already excludes credit-card and loan transfer mechanics; use this instead of summing other reports. | `yearMonth?` *xor* `monthsBack?` (default 6, max 24); `currentYearMonth?`, `workspaceId?` |
| `kualia_get_spending_report` | Gross inflow and outflow activity by category, group, and merchant for a single month or range. An entity can appear in both directions; prefer `get_monthly_summary` for clean spending, income, and savings totals. | `yearMonth?` *xor* `monthsBack?`; `currentYearMonth?`, `workspaceId?` |
| `kualia_get_income_summary` | Income and inflow summary for a month or range, sourced from pre-aggregated workspace data. | `yearMonth?` *xor* `monthsBack?` (default 1); `currentYearMonth?`, `workspaceId?` |
| `kualia_get_category_rollup` | Multi-month per-category totals: total assigned, total inflow, total outflow. | `monthsBack?` (default 6, max 24), `currentYearMonth?`, `workspaceId?` |
| `kualia_get_account_balances_report` | Monthly account balance history across every account, with multi-currency support. | `monthsBack?`, `currentYearMonth?`, `workspaceId?` |
## Common parameters
* **`workspaceId`** is optional on every tool and defaults to the user's active workspace. Pass it explicitly only when the user has multiple workspaces and you need a non-default one. Get ids from `kualia_list_workspaces`.
* **`yearMonth`** is `YYYYMM` (e.g. `202604` for April 2026). **`currentDate`** is `YYYY-MM-DD`.
* **Batch limits:** transactions up to **200** per call; categories up to **50**; category groups up to **10**.
* **Money** is encoded as a signed decimal string in the workspace currency, with at most `minorUnit` fractional digits (USD = 2 → `"51.08"`; JPY = 0 → `"5108"`; KWD = 3 → `"5.108"`). Each money-bearing response carries `currencyCode`, `minorUnit`, and `amountEncoding: 'decimal_string'`. Don't scale by 100.
All tools respect per-workspace permissions. The server only returns and modifies data your account can access.
Agent-driven updates also preserve a transaction's `reviewStatus`: rows created or edited through MCP stay as **Needs
Review** until you mark them reviewed in the app yourself.
# Importing Data
Source: https://docs.kualia.com/more/importing-data
Bring your existing budget data into Kualia
## Overview
Switching to Kualia? You can import your existing budget data to get started quickly.
## YNAB Import
Kualia supports importing data from **You Need A Budget (YNAB)**. This lets you bring over your:
* Categories and category groups
* Transactions
* Account balances
### Import Status
The import process goes through several stages:
1. **Pending** - import requested
2. **Parsing** - reading and validating your data
3. **Importing** - creating records in Kualia
4. **Completed** - all done
If something goes wrong, the status will show **Failed** with an error message.
# Notifications
Source: https://docs.kualia.com/more/notifications
Stay informed about upcoming bills and budget events
## Overview
Kualia sends push notifications to keep you on top of your finances. Notifications are delivered to your iOS device.
## Planned Transaction Reminders
When you create a planned transaction, you can enable a reminder with these timing options:
| Reminder Timing | Description |
| --------------- | ------------------------------------------- |
| On due date | Notified on the day the payment is expected |
| 1 day before | One day before the due date |
| 2 days before | Two days before the due date |
| 1 week before | One week before the due date |
| 1 month before | One month before the due date |
### How Reminders Work
1. Kualia schedules the reminder from the plan's due date
2. A background job checks for due reminders periodically
3. When a reminder is due, a push notification is sent to your iOS device via APNs
4. For recurring plans, the next reminder is scheduled from the next due date
### Configuring Reminders
To set up a reminder:
1. Open a planned transaction or create a new one
2. Select your preferred reminder timing
3. Save
## Notification Delivery
Notifications are delivered via Apple Push Notification service (APNs) to your registered iOS devices. Make sure:
* Push notifications are enabled for Kualia in your iOS Settings
* You're signed in to the app on your device
# Subscription & Pricing
Source: https://docs.kualia.com/more/subscription
Kualia subscription plans and billing
## Overview
Kualia offers a subscription model to access all features. Subscriptions are managed through RevenueCat across all platforms.
## Plans
| Plan | Description |
| ------------ | -------------------------------------- |
| **Trial** | Try Kualia free for a limited time |
| **Monthly** | Pay month-to-month |
| **Yearly** | Annual billing with savings |
| **Lifetime** | One-time purchase for permanent access |
## Family Sharing
An active subscription can cover a family group. The group manager can invite up to five additional people, for six people total including the manager.
Family members can use Kualia through their own subscription or through the group manager's active subscription. If a family member does not have their own active subscription and the group manager's subscription expires, that member is blocked until access is restored.
See [Family Sharing](/features/family-sharing) for member limits, visibility, and permissions.
## Subscribing
You can subscribe through:
* **iOS App Store** - in-app purchase via Apple
* **Web** - via Stripe
## Managing Your Subscription
### iOS
Manage your subscription through **Settings > Apple ID > Subscriptions** on your iPhone.
### Web
## Trial
New users get a free trial to explore all of Kualia's features.
## FAQ
# iOS App
Source: https://docs.kualia.com/platforms/ios-app
Budget on the go with the native iOS app
## Overview
The Kualia iOS app is a native SwiftUI application designed for iPhone. It gives you full access to your budget wherever you are.
## Key Features
* **Full budget management** - view and assign money to categories
* **Quick transaction entry** - add transactions on the go
* **Transaction review** - review and categorize imported transactions
* **Push notifications** - reminders for upcoming planned transactions
* **Home screen widgets** - glance at your budget without opening the app
* **Bank connections** - connect and manage bank links
* **Real-time sync** - instant sync with the web app via Convex
## Requirements
* iOS 17.0 or later
* iPhone
## Download
Download from the [App Store](https://apps.apple.com/us/app/envelope-budget-kualia/id6466455367).
## Push Notifications
The iOS app supports push notifications for:
* **Planned transaction reminders** - get notified before bills are due
* **Other alerts** - important account updates
See [Notifications](/more/notifications) for configuration details.
# Web App
Source: https://docs.kualia.com/platforms/web-app
Manage your budget from any browser
## Overview
The Kualia web app is the full-featured way to manage your budget from any device with a browser.
**URL:** [app.kualia.com](https://app.kualia.com)
## Key Features
* **Full budget management** - assign money, manage categories, set targets
* **Transaction entry & review** - add, edit, split, and categorize transactions
* **Account management** - add accounts, connect banks, reconcile
* **Planned transactions** - schedule one-time or recurring transactions with automatic or manual entry
* **Real-time sync** - changes appear instantly across all connected devices
* **Search & filtering** - find any transaction quickly
## Technology
The web app is built with **Angular** and features:
* Real-time data powered by Convex
* Responsive design for desktop and mobile browsers
* Secure authentication via Clerk
## Getting Started
1. Visit [app.kualia.com](https://app.kualia.com)
2. Sign up with your email or Google account
3. Create your workspace and start budgeting
# Widgets
Source: https://docs.kualia.com/platforms/widgets
View your budget at a glance from your home screen
## Overview
Kualia offers iOS home screen widgets that let you see key budget information without opening the app.
## How Widgets Work
Widgets use a dedicated authentication system separate from your main app session. When you set up widgets:
1. The app creates a long-lived widget token
2. The widget uses this token to fetch data via secure HTTP endpoints
3. Data refreshes periodically based on iOS widget refresh schedules
This means widgets work even when you're not actively logged into the app.
## Available Widgets
Widget details and types are being expanded. Check back for updates on available widget configurations.
## Setting Up Widgets
Enter edit mode on your iPhone home screen.
Search for "Kualia" in the widget gallery.
Select the widget size and type you want.
Place the widget where you'd like it.
## Security
Widget tokens can be revoked from within the app if needed. Revoking tokens will stop all widgets from displaying data until new tokens are generated.
# Quickstart
Source: https://docs.kualia.com/quickstart
Get up and running with Kualia in minutes
## 1. Create Your Account
Sign up using your email (via one-time passcode) or Google account. Authentication is handled securely through Clerk.
## 2. Create a Workspace
After signing up, you'll create your first **workspace**. A workspace is your budgeting environment that holds all your accounts, categories, and transactions.
## 3. Set Up Your Categories
Kualia creates some default category groups for you. Customize them to match how you spend:
* **Category Groups** organize related categories (e.g., "Housing", "Food", "Transportation")
* **Categories** are your individual envelopes (e.g., "Rent", "Groceries", "Gas")
## 4. Add Your Accounts
Add your financial accounts to track balances:
* **Checking & Savings** - your everyday bank accounts
* **Credit Cards** - track spending and payments
* **Cash** - for physical cash tracking
* **Investments** - 401k, IRA, brokerage accounts
* **Loans** - mortgage, auto, student loans
You can add accounts manually or [connect your bank](/features/bank-connections) for automatic imports.
## 5. Set Your Monthly Income
Tell Kualia how much you expect to earn each month. This helps with budgeting guidance and target recommendations.
## 6. Assign Your Money
Head to the budget view and start [assigning money](/features/assigning-money) to your categories. The goal is to give every dollar a job.
## Next Steps
Understand the methodology behind Kualia.
Automate your category funding goals.
Import transactions automatically.
Schedule upcoming bills, income, and transfers.