> ## Documentation Index
> Fetch the complete documentation index at: https://docs.setaside.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Expenses

> Expenses: Set Aside Money developer API reference.

An Expense is money you have set aside for a known cost, so it is not part of your Free-to-Spend.
The API uses the same three kinds the app does: regular Expenses, Goals, and credit card Expenses.

## List Expenses

> **GET** `/v1/expenses` · Required scope: `data.read`

```bash theme={null}
curl https://api.setaside.money/v1/expenses \
  -H "Authorization: Bearer $SETASIDE_API_KEY"
```

```json theme={null}
[
  {
    "id": "5d4c3b2a-1f0e-4d9c-8b7a-6e5f4d3c2b1a",
    "name": "Car insurance",
    "type": "expense",
    "target_amount": 84000,
    "balance": 42000
  }
]
```

| Field | Type | Notes |
| - | - | - |
| `id` | uuid | |
| `name` | string | |
| `type` | string | `expense`, `goal`, or `credit_card`. |
| `target_amount` | integer, nullable | Cents. What you are working towards. |
| `balance` | integer | Cents currently set aside. |

## Expense totals

> **GET** `/v1/expenses/summary` · Required scope: `data.read`

Rollups across every Expense, including the total set aside.

## Expense groups

> **GET** `/v1/expense-groups` · Required scope: `data.read`

The groups Expenses are organised into.

## List transfers

> **GET** `/v1/expense-transfers` · Required scope: `data.read`

Past movements of money between Expenses.

## Move money between Expenses

> **POST** `/v1/expense-transfers` · Required scope: `data.write`

Moves an amount from one Expense to another. Nothing leaves your bank; this changes what the money
is earmarked for.

| Field | Required | Notes |
| - | - | - |
| `from_expense_id` | yes | |
| `to_expense_id` | yes | |
| `amount` | yes | Integer cents, positive. |
| `note` | no | Up to 200 characters. |

```bash theme={null}
curl -X POST https://api.setaside.money/v1/expense-transfers \
  -H "Authorization: Bearer $SETASIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rebalance-2026-08-08" \
  -d '{
    "from_expense_id": "5d4c3b2a-1f0e-4d9c-8b7a-6e5f4d3c2b1a",
    "to_expense_id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
    "amount": 5000,
    "note": "Covering the vet bill"
  }'
```

Always send an `Idempotency-Key` here. This is the one endpoint where a duplicated request moves
money twice, and the key is honoured all the way down to the ledger, so a retried request carrying
the same key is recorded once.

## Funding schedules

> **GET** `/v1/funding-schedules` · Required scope: `data.read`

The paydays that fund your Expenses, and when each next runs. Read only in this version; running a
schedule stays in the app.

## Categories

> **GET** `/v1/categories` · Required scope: `data.read`

The category catalog, for use as `category_id` on a transaction.

## Envelope funding fields

Expense reads include priority, recurrence, and Fund Ahead settings, plus calculated reserve and contribution fields. The total `balance` already includes `extraReserve`; do not add it again.

These additions do not expose internal funding-calculation or suggestion-resolution routes as personal-key endpoints. Use only documented public `/v1` routes.

[Read the Fund Ahead guide](/guides/fund-ahead).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.