Transactions | Open Ledger Documentation

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