Skip to main content

​
Get transactions

GET /api/v1/transactions
Retrieve all transactions for the authenticated user with support for filtering by date, account, category, vendor, and more.

​
Query parameters

​
month
string
Filter transactions by month in YYYY-MM format. Cannot be used with start_date or end_date
​
start_date
string
Filter transactions on or after this date (YYYY-MM-DD). Cannot be used with month
​
end_date
string
Filter transactions on or before this date (YYYY-MM-DD). Cannot be used with month
​
category_id
string
Filter transactions by category UUID
​
account_id
string
Filter transactions by account UUID
​
vendor_id
string
Filter transactions by vendor UUID
​
type
string
Filter by transaction type. Options: income, payment, starting
​
description_contains
string
Filter transactions where description contains this text (case-insensitive)
​
vendor
string
Filter transactions where vendor name contains this text (case-insensitive)
​
amount_min
number
Filter transactions with amount greater than or equal to this value
​
amount_max
number
Filter transactions with amount less than or equal to this value
​
include
string
Comma-separated list of related data to include. Options: account, category, vendor
​
fields
string
Comma-separated list of fields to return. Available fields: id, account_id, amount, category_id, created_at, date, description, type, user_id, vendor, vendor_id
​
sort
string
default:"date"
Field to sort by. Options: date, created_at, amount, vendor, type
​
order
string
default:"desc"
Sort order. Options: asc, desc
​
limit
integer
default:"100"
Maximum number of results to return (1-1000)
​
offset
integer
default:"0"
Number of results to skip for pagination
​
cursor
string
Cursor for pagination. Cannot be used with offset

​
Response fields

​
data
array
Array of transaction objects
​
id
string
Unique transaction identifier (UUID)
​
account_id
string
Account UUID this transaction belongs to
​
amount
number
Transaction amount
​
category_id
string | null
Category UUID for this transaction
​
created_at
string
Transaction creation timestamp (ISO 8601)
​
date
string
Transaction date (YYYY-MM-DD)
​
description
string | null
Transaction description
​
type
string
Transaction type: income, payment, or starting
​
user_id
string
User UUID who owns this transaction
​
vendor
string
Vendor name
​
vendor_id
string | null
Vendor UUID
​
account
object
Account details (only included when include=account)
​
id
string
Account UUID
​
name
string
Account name
​
type
string
Account type
​
category
object
Category details (only included when include=category)
​
id
string
Category UUID
​
name
string
Category name
​
group
string
Group UUID
​
vendor_details
object
Vendor details (only included when include=vendor)
​
id
string
Vendor UUID
​
name
string
Vendor name
​
meta
object
Pagination and metadata
​
total
integer
Total number of matching transactions
​
returned
integer
Number of transactions returned in this response
​
limit
integer
Maximum results per page
​
offset
integer
Current offset
​
next_cursor
string | null
Cursor for the next page, or null if no more results
​
sort
string
Field used for sorting
​
order
string
Sort order applied
​
includes
array
List of included related data
​
month
string | null
Month filter applied
​
start_date
string | null
Start date filter applied
​
end_date
string | null
End date filter applied

​
Example request

curl -X GET "https://api.cashcat.app/api/v1/transactions?month=2024-03&type=payment&include=account,category&sort=date&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example response

{
  "data": [
    {
      "id": "t1u2v3w4-x5y6-7890-tuvw-345678901234",
      "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": -45.67,
      "category_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "created_at": "2024-03-15T14:30:00Z",
      "date": "2024-03-15",
      "description": "Weekly grocery shopping",
      "type": "payment",
      "user_id": "u1v2w3x4-y5z6-7890-uvwx-456789012345",
      "vendor": "Whole Foods",
      "vendor_id": "v1w2x3y4-z5a6-7890-vwxy-567890123456",
      "account": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Main Checking",
        "type": "checking"
      },
      "category": {
        "id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
        "name": "Groceries",
        "group": "g1h2i3j4-k5l6-7890-ghij-234567890123"
      }
    }
  ],
  "meta": {
    "total": 1,
    "returned": 1,
    "limit": 100,
    "offset": 0,
    "next_cursor": null,
    "sort": "date",
    "order": "desc",
    "includes": ["account", "category"],
    "month": "2024-03",
    "start_date": "2024-03-01",
    "end_date": "2024-03-31"
  }
}

​
Create transaction

POST /api/v1/transactions
Create a new transaction for the authenticated user. Transactions automatically update account balances and category budgets.

​
Headers

​
Idempotency-Key
string
Optional idempotency key (max 200 characters) to prevent duplicate transactions. If provided, the same key will return the existing transaction instead of creating a duplicate.

​
Query parameters

​
dry_run
boolean
default:"false"
If true, validates the transaction without creating it. Returns validation result.

​
Request body

​
amount
number
required
Transaction amount. Negative for expenses/payments, positive for income
​
date
string
required
Transaction date in YYYY-MM-DD format
​
type
string
default:"payment"
Transaction type: payment, income, or starting
​
category_id
string
Category UUID. Required when type=payment
​
account_id
string
Account UUID. If omitted, uses the default account
​
description
string
Optional transaction description
​
vendor
string
Optional vendor name
​
vendor_id
string
Optional vendor UUID

​
Response

Returns the created transaction object with metadata.
​
data
object
The created transaction object with all fields populated
​
meta
object
​
created
boolean
Always true for new creations
​
idempotent_replay
boolean
true if an existing transaction was returned due to idempotency key match
​
dry_run
boolean
true if this was a validation-only request

​
Example request

curl -X POST "https://api.cashcat.app/api/v1/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: purchase-2024-03-15-001" \
  -d '{
    "amount": -45.67,
    "date": "2024-03-15",
    "type": "payment",
    "category_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "description": "Weekly grocery shopping",
    "vendor": "Whole Foods"
  }'

​
Example response

{
  "data": {
    "id": "t1u2v3w4-x5y6-7890-tuvw-345678901234",
    "user_id": "u1v2w3x4-y5z6-7890-uvwx-456789012345",
    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": -45.67,
    "date": "2024-03-15",
    "type": "payment",
    "category_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
    "description": "Weekly grocery shopping",
    "vendor": "Whole Foods",
    "vendor_id": null,
    "created_at": "2024-03-15T14:30:00Z"
  },
  "meta": {
    "created": true
  }
}
Transactions automatically affect account balances and budget calculations. For payment type transactions, the amount is deducted from the specified category’s budget.

Build docs developers (and LLMs) love

Get started for freeTalk to us