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

curl https://api.setaside.money/v1/expenses \
  -H "Authorization: Bearer $SETASIDE_API_KEY"

[
  {
    "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.

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.