Overview
Transactions represent financial activities in Budget Bee. They support categories, tags, line items, and can be filtered by various criteria.
Base URL
{NEXT_PUBLIC_PG_REST_URL}/transactions
Authorization
All transaction endpoints require authentication via JWT token:
Authorization: Bearer {JWT_TOKEN}
List Transactions
Retrieve a list of transactions. Results are automatically filtered based on user/organization context.
Query Parameters
Columns to return. Default: * (all columns)
Sort order. Example: transaction_date.desc or amount.asc
Maximum number of results to return
Number of results to skip (for pagination)
Filter by category ID. Use eq.{uuid} format
Filter by status. Values: paid, pending, failed
Filter by date. Use operators like gte.2024-01-01 or lte.2024-12-31
Filter by amount. Use operators like gt.100 or lt.1000
Request Example
curl -X GET "{NEXT_PUBLIC_PG_REST_URL}/transactions?order=transaction_date.desc&limit=50" \
-H "Authorization: Bearer {JWT_TOKEN}" \
-H "Content-Type: application/json"
Response
Unique transaction identifier
Transaction amount (decimal with 2 places)
Currency code (default: “usd”)
Organization ID (null for personal transactions)
External reference ID (for imports)
Reference or invoice number
Transaction status: paid, pending, failed
Source of transaction (default: “manual”)
Additional metadata as JSON
When the transaction occurred
When the record was created
Response Example
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 125.50,
"currency": "usd",
"user_id": "usr_abc123",
"organization_id": "org_456",
"external_id": null,
"category_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"reference_no": "INV-2024-001",
"name": "Office Supplies",
"description": "Pens, notebooks, and printer paper",
"status": "paid",
"source": "manual",
"metadata": {
"vendor": "Office Depot",
"payment_method": "credit_card"
},
"transaction_date": "2024-01-15T14:30:00Z",
"created_at": "2024-01-15T14:32:00Z",
"updated_at": "2024-01-15T14:32:00Z"
}
]
Get Transaction
Retrieve a single transaction by ID.
GET /transactions?id=eq.{transaction_id}
Request Example
curl -X GET "{NEXT_PUBLIC_PG_REST_URL}/transactions?id=eq.550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer {JWT_TOKEN}" \
-H "Accept: application/vnd.pgrst.object+json"
Add Accept: application/vnd.pgrst.object+json header to return a single object instead of an array.
Response Example
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 125.50,
"currency": "usd",
"name": "Office Supplies",
"category_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"transaction_date": "2024-01-15T14:30:00Z"
}
Create Transaction
Create a new transaction.
Request Body
Currency code (default: “usd”)
Status: paid, pending, or failed (default: “paid”)
Source identifier (default: “manual”)
Reference or invoice number
External system reference ID
Additional metadata as JSON
Transaction date (default: current timestamp)
User ID (auto-populated from JWT)
Organization ID (auto-populated from JWT if in org context)
Request Example
curl -X POST "{NEXT_PUBLIC_PG_REST_URL}/transactions" \
-H "Authorization: Bearer {JWT_TOKEN}" \
-H "Content-Type: application/json" \
-H "Prefer: return=representation" \
-d '{
"amount": 89.99,
"name": "Monthly Software Subscription",
"description": "Adobe Creative Cloud",
"category_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "paid",
"source": "manual",
"currency": "usd",
"transaction_date": "2024-01-15T00:00:00Z",
"metadata": {
"subscription": true,
"recurring": "monthly"
}
}'
Include Prefer: return=representation header to return the created transaction in the response.
Response Example
{
"id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"amount": 89.99,
"currency": "usd",
"user_id": "usr_abc123",
"organization_id": "org_456",
"category_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Monthly Software Subscription",
"description": "Adobe Creative Cloud",
"status": "paid",
"source": "manual",
"metadata": {
"subscription": true,
"recurring": "monthly"
},
"transaction_date": "2024-01-15T00:00:00Z",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
Update Transaction
Update an existing transaction.
PATCH /transactions?id=eq.{transaction_id}
Request Body
Any transaction fields that need to be updated. Only include fields you want to change.
Request Example
curl -X PATCH "{NEXT_PUBLIC_PG_REST_URL}/transactions?id=eq.550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer {JWT_TOKEN}" \
-H "Content-Type: application/json" \
-H "Prefer: return=representation" \
-d '{
"amount": 95.00,
"status": "paid",
"description": "Updated description"
}'
Response Example
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 95.00,
"status": "paid",
"description": "Updated description",
"updated_at": "2024-01-16T09:15:00Z"
}
The updated_at field is automatically updated via database trigger.
Delete Transaction
Delete a transaction permanently.
DELETE /transactions?id=eq.{transaction_id}
Request Example
curl -X DELETE "{NEXT_PUBLIC_PG_REST_URL}/transactions?id=eq.550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer {JWT_TOKEN}"
Response
Returns 204 No Content on successful deletion.
Deleting a transaction will cascade delete related records like line items and tag associations.
Bulk Operations
Create Multiple Transactions
Create multiple transactions in a single request.
Request Example
curl -X POST "{NEXT_PUBLIC_PG_REST_URL}/transactions" \
-H "Authorization: Bearer {JWT_TOKEN}" \
-H "Content-Type: application/json" \
-H "Prefer: return=representation" \
-d '[
{
"amount": 50.00,
"name": "Groceries",
"category_id": "cat_food_123",
"transaction_date": "2024-01-15T00:00:00Z"
},
{
"amount": 30.00,
"name": "Gas",
"category_id": "cat_travel_456",
"transaction_date": "2024-01-15T00:00:00Z"
}
]'
Update Multiple Transactions
Update multiple transactions matching a filter.
PATCH /transactions?status=eq.pending
curl -X PATCH "{NEXT_PUBLIC_PG_REST_URL}/transactions?status=eq.pending" \
-H "Authorization: Bearer {JWT_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"status": "paid"
}'
Advanced Filtering
Filter by Date Range
GET /transactions?transaction_date=gte.2024-01-01&transaction_date=lte.2024-01-31
Filter by Amount Range
GET /transactions?amount=gte.100&amount=lte.500
Filter by Multiple Statuses
GET /transactions?status=in.(paid,pending)
Search by Name
GET /transactions?name=ilike.*subscription*
Complex Filters with OR
GET /transactions?or=(status.eq.paid,amount.gt.1000)
Access Control
Transaction access is controlled by organization roles:
Owner
Full access: list, get, create, update, delete
Admin
Full access: list, get, create, update, delete
Editor
Full access: list, get, create, update, delete
Viewer
Read-only: list, get
Personal vs Organization Transactions
- Personal:
organization_id is null, accessible only by the user
- Organization:
organization_id is set, accessible by organization members based on their role
Error Responses
401 Unauthorized
{
"message": "JWT expired",
"code": "PGRST301"
}
403 Forbidden
{
"message": "permission denied for table transactions",
"code": "42501"
}
404 Not Found
PostgREST returns an empty array instead of 404 when no rows match the query.
400 Bad Request
{
"message": "invalid input syntax for type uuid",
"code": "22P02"
}
