Transactions

The transactions endpoints allow you to create, retrieve, update, and manage financial transactions for your entities. Transactions represent the core financial activity in your Open Ledger account.

Transaction Objects

A transaction in Open Ledger represents a financial event that affects two ledger accounts through debits and credits. Each transaction consists of:

1 {
2   "id": "txn_123abc",
3   "instance_id": "inst_456def",
4   "timestamp": "2023-05-15T10:30:00Z",
5   "amount": "2500.00",
6   "currency": "USD",
7   "description": "Office Rent Payment",
8   "debit_account_id": "acc_rent",
9   "credit_account_id": "acc_cash",
10   "status": "PENDING",
11   "tb_transfer_id": "tb_789ghi",
12   "metadata": {
13     "invoiceId": "INV-2023-001",
14     "paymentMethod": "bank_transfer"
15   },
16   "created_at": "2023-05-15T10:30:00Z",
17   "updated_at": "2023-05-15T10:30:00Z",
18   "entity_id": "entity_012jkl",
19   "created_by": "user_345mno",
20   "updated_by": "user_345mno"
21 }

Transaction Status

Transactions can have the following statuses:

PENDING: Initial state, transaction is recorded but not finalized
CLEARED: Transaction has been cleared (e.g., by a bank)
RECONCILED: Transaction has been manually reconciled
POSTED: Transaction has been permanently posted to the ledger
REVERSED: Transaction has been reversed
EXPIRED: Transaction has expired (e.g., a pending transaction that wasn’t completed)

Create a Transaction

Create a new transaction for an entity.

1 POST /v1/transactions
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Headers

Header	Value
`X-entity-ID`	Your entity ID

Request Body

Field	Type	Description
`instance_id`	string	ID of the instance this transaction belongs to
`entity_id`	string	ID of the entity this transaction belongs to
`timestamp`	string	Transaction date and time
`description`	string	Description of the transaction
`amount`	string	Transaction amount
`currency`	string	Currency code (USD, EUR, etc.) (default: USD)
`debit_account_id`	string	ID of the account to debit
`credit_account_id`	string	ID of the account to credit
`status`	enum	Transaction status (default: PENDING)
`metadata`	object	Additional metadata (optional)

1 {
2   "instance_id": "inst_456def",
3   "entity_id": "entity_012jkl",
4   "timestamp": "2023-05-15T14:22:00Z",
5   "description": "Office Supplies Purchase",
6   "amount": "250.00",
7   "currency": "USD",
8   "debit_account_id": "acc_office_supplies",
9   "credit_account_id": "acc_bank",
10   "status": "PENDING",
11   "metadata": {
12     "receiptId": "R12345",
13     "vendor": "Office Depot"
14   }
15 }

Response

1 {
2   "id": "txn_456def",
3   "instance_id": "inst_456def",
4   "timestamp": "2023-05-15T14:22:00Z",
5   "description": "Office Supplies Purchase",
6   "amount": "250.00",
7   "currency": "USD",
8   "debit_account_id": "acc_office_supplies",
9   "credit_account_id": "acc_bank",
10   "status": "PENDING",
11   "metadata": {
12     "receiptId": "R12345",
13     "vendor": "Office Depot"
14   },
15   "created_at": "2023-05-15T14:22:00Z",
16   "updated_at": "2023-05-15T14:22:00Z",
17   "entity_id": "entity_012jkl",
18   "created_by": "user_345mno"
19 }

List Transactions

Retrieve a list of transactions for an entity with optional filters.

1 GET /v1/transactions
2 Authorization: Bearer {access_token}

Headers

Header	Value
`X-entity-ID`	Your entity ID

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of transactions to return (default: 25, max: 100)
`offset`	integer	Number of transactions to skip (for pagination)
`debitAccountId`	string	Filter by debit account ID
`creditAccountId`	string	Filter by credit account ID
`from`	string	Start date/time
`to`	string	End date/time
`status`	string	Filter by status
`minAmount`	string	Minimum transaction amount
`maxAmount`	string	Maximum transaction amount

Response

1 {
2   "data": [
3     {
4       "id": "txn_456def",
5       "instance_id": "inst_456def",
6       "timestamp": "2023-05-15T14:22:00Z",
7       "description": "Office Supplies Purchase",
8       "amount": "250.00",
9       "currency": "USD",
10       "debit_account_id": "acc_office_supplies",
11       "credit_account_id": "acc_bank",
12       "status": "PENDING",
13       "metadata": {
14         "receiptId": "R12345",
15         "vendor": "Office Depot"
16       },
17       "created_at": "2023-05-15T14:22:00Z",
18       "updated_at": "2023-05-15T14:22:00Z"
19     }
20     // Additional transactions...
21   ],
22   "meta": {
23     "total": 157,
24     "limit": 25,
25     "offset": 0
26   }
27 }

Get Transactions By Month

Retrieve transactions organized by month.

1 GET /v1/transactions/by-month
2 Authorization: Bearer {access_token}

Headers

Header	Value
`X-entity-ID`	Your entity ID

Query Parameters

Parameter	Type	Description
`year`	integer	Year to filter by
`month`	integer	Month to filter by (1-12)
`limit`	integer	Number of transactions per month (default: 25)

Response

1 {
2   "month": 5,
3   "year": 2023,
4   "transactions": [
5     {
6       "id": "txn_456def",
7       "description": "Office Supplies Purchase",
8       "amount": "250.00",
9       "timestamp": "2023-05-15T14:22:00Z",
10       "status": "PENDING"
11       // Additional transaction details...
12     }
13     // Additional transactions...
14   ],
15   "totals": {
16     "count": 45,
17     "amount": "15250.75"
18   }
19 }

Update a Transaction

Update an existing transaction.

1 PUT /v1/transactions
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Headers

Header	Value
`X-entity-ID`	Your entity ID

Request Body

Fields are optional for updates. Only include the fields you want to update. You must include the transaction ID to identify which transaction to update.

1 {
2   "id": "txn_456def",
3   "description": "Updated Office Supplies Purchase",
4   "status": "CLEARED",
5   "metadata": {
6     "receiptId": "R12345",
7     "vendor": "Office Depot",
8     "department": "Marketing"
9   }
10 }

Response

1 {
2   "id": "txn_456def",
3   "instance_id": "inst_456def",
4   "timestamp": "2023-05-15T14:22:00Z",
5   "description": "Updated Office Supplies Purchase",
6   "amount": "250.00",
7   "currency": "USD",
8   "debit_account_id": "acc_office_supplies",
9   "credit_account_id": "acc_bank",
10   "status": "CLEARED",
11   "metadata": {
12     "receiptId": "R12345",
13     "vendor": "Office Depot",
14     "department": "Marketing"
15   },
16   "created_at": "2023-05-15T14:22:00Z",
17   "updated_at": "2023-05-15T14:30:45Z",
18   "entity_id": "entity_012jkl",
19   "created_by": "user_345mno",
20   "updated_by": "user_345mno"
21 }

Delete a Transaction

Delete an existing transaction.

1 DELETE /v1/transactions
2 Authorization: Bearer {access_token}

Headers

Header	Value
`X-entity-ID`	Your entity ID

Query Parameters

Parameter	Type	Description
`id`	string	Transaction ID to delete

Response

A successful request returns a 204 No Content response with no body.

Deleting a transaction will permanently remove it from your ledger. This action cannot be undone. Consider using the transaction status (e.g., REVERSED) instead of deletion for proper accounting audit trails.

Approve a Transaction

Approve a pending transaction.

1 POST /v1/transactions/approve
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Headers

Header	Value
`X-entity-ID`	Your entity ID

Request Body

1 {
2   "id": "txn_456def"
3 }

Response

1 {
2   "id": "txn_456def",
3   "status": "POSTED",
4   "updated_at": "2023-05-15T16:45:22Z"
5 }

Categorize a Transaction

Assign category information to a transaction.

1 POST /v1/transactions/categorize
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Headers

Header	Value
`X-entity-ID`	Your entity ID

Request Body

1 {
2   "id": "txn_456def",
3   "category_id": "cat_123abc",
4   "sub_category_id": "subcat_456def"
5 }

Response

1 {
2   "id": "txn_456def",
3   "category_id": "cat_123abc",
4   "sub_category_id": "subcat_456def",
5   "updated_at": "2023-05-15T16:55:30Z"
6 }

Search Transactions

1 POST /v1/transactions/search
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Search for transactions using advanced criteria.

Headers

Header	Value
`X-entity-ID`	Your entity ID

Request Body

1 {
2   "query": "office supplies",
3   "filters": {
4     "dateRange": {
5       "start": "2023-01-01",
6       "end": "2023-06-30"
7     },
8     "amount": {
9       "min": 100,
10       "max": 500
11     },
12     "status": ["PENDING", "POSTED"],
13     "accounts": ["acc_office_supplies"]
14   },
15   "sort": {
16     "field": "amount",
17     "direction": "desc"
18   },
19   "limit": 25,
20   "offset": 0
21 }

Response

1 {
2   "results": [
3     {
4       "id": "txn_456def",
5       "description": "Office Supplies Purchase",
6       "amount": "250.00",
7       "timestamp": "2023-05-15T14:22:00Z",
8       "status": "PENDING"
9       // Additional transaction details...
10     }
11     // Additional transactions...
12   ],
13   "meta": {
14     "total": 12,
15     "limit": 25,
16     "offset": 0
17   }
18 }

Transaction Chat

Get AI-assisted answers to questions about transactions.

1 GET /v1/transactions/chat
2 Authorization: Bearer {access_token}

Headers

Header	Value
`X-entity-ID`	Your entity ID

Query Parameters

Parameter	Type	Description
`query`	string	Natural language question about transactions
`timeframe`	string	Optional timeframe to focus on (e.g., “last_month”)

Response

1 {
2   "answer": "In May 2023, you spent a total of $3,245.75 on office supplies across 8 transactions. The largest purchase was $750.00 at Office Depot on May 10th.",
3   "transactions": [
4     {
5       "id": "txn_456def",
6       "description": "Office Supplies Purchase",
7       "amount": "250.00",
8       "timestamp": "2023-05-15T14:22:00Z"
9     }
10     // Additional relevant transactions...
11   ],
12   "summary": {
13     "total_amount": 3245.75,
14     "transaction_count": 8,
15     "average_amount": 405.72
16   }
17 }

Suggest Transaction Categories

Get AI-powered suggestions for transaction categorization.

1 POST /v1/transactions/suggest-categories/{entityId}
2 Authorization: Bearer {access_token}
3 Content-Type: application/json

Path Parameters

Parameter	Type	Description
`entityId`	string	ID of the entity

Request Body

1 {
2   "transactions": [
3     {
4       "id": "txn_123",
5       "description": "AWS Monthly Services",
6       "amount": 329.99,
7       "date": "2023-06-15"
8     },
9     {
10       "id": "txn_124",
11       "description": "Uber trip to airport",
12       "amount": 45.5,
13       "date": "2023-06-16"
14     }
15   ]
16 }

Response

1 {
2   "success": true,
3   "suggestions": [
4     {
5       "transaction_id": "txn_123",
6       "suggested_accounts": [
7         {
8           "id": "acc_cloud_services",
9           "name": "Cloud Services",
10           "type": "EXPENSE",
11           "confidence": 0.95
12         },
13         {
14           "id": "acc_software",
15           "name": "Software Subscriptions",
16           "type": "EXPENSE",
17           "confidence": 0.82
18         }
19       ]
20     },
21     {
22       "transaction_id": "txn_124",
23       "suggested_accounts": [
24         {
25           "id": "acc_travel",
26           "name": "Travel Expenses",
27           "type": "EXPENSE",
28           "confidence": 0.91
29         },
30         {
31           "id": "acc_transportation",
32           "name": "Transportation",
33           "type": "EXPENSE",
34           "confidence": 0.88
35         }
36       ]
37     }
38   ]
39 }

Error Codes

Error Code	Description
`invalid_transaction`	Transaction validation failed
`duplicate_transaction`	Transaction already exists
`account_not_found`	Referenced account does not exist
`insufficient_balance`	Insufficient balance for the transaction
`permission_denied`	User does not have permission for this action

Next Steps

Now that you understand how to manage transactions, you can explore related API resources:

Ledger Accounts

Manage your chart of accounts

Reports

Generate financial reports