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   "entityId": "entity_012jkl",
4   "timestamp": "2023-05-15T10:30:00Z",
5   "amount": 2500.00,
6   "currency": "USD",
7   "description": "Office Rent Payment",
8   "debitAccountId": "acc_rent",
9   "creditAccountId": "acc_cash",
10   "status": "PENDING",
11   "metadata": {
12     "invoiceId": "INV-2023-001",
13     "paymentMethod": "bank_transfer"
14   },
15   "date": "2023-05-15T10:30:00Z",
16   "transaction_date": "2023-05-15T10:30:00Z",
17   "accountType": "EXPENSE",
18   "financialType": "RENT",
19   "category": "Office Expenses",
20   "category_id": "cat_5678",
21   "debitAccount": {
22     "id": "acc_rent",
23     "name": "Rent Expense",
24     "type": "EXPENSE",
25     "financialType": "RENT",
26     "code": "5001",
27     "subTypeCode": "RENT",
28     "isCategory": false
29   },
30   "creditAccount": {
31     "id": "acc_cash",
32     "name": "Cash",
33     "type": "ASSET",
34     "financialType": "CASH",
35     "code": "1001",
36     "subTypeCode": "CHECKING",
37     "isCategory": false
38   },
39   "plaid_account": {
40     "id": "plaid_123",
41     "name": "Checking Account",
42     "type": "CHECKING",
43     "subtype": "checking",
44     "mask": "1234",
45     "institution_id": "ins_123"
46   },
47   "createdAt": "2023-05-15T10:30:00Z",
48   "updatedAt": "2023-05-15T10:30:00Z"
49 }

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)
POSTED: Transaction has been permanently posted to the ledger

Get Transactions

Retrieve transactions for an entity with cursor-based pagination.

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

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity to get transactions for (required)
`cursor`	string	Cursor for pagination (optional)
`pageSize`	integer	Number of transactions per page (default: 50)

Response

1 {
2   "transactions": [
3     {
4       "id": "txn_456def",
5       "entityId": "entity_012jkl",
6       "timestamp": "2023-05-15T14:22:00Z",
7       "amount": 250.00,
8       "currency": "USD",
9       "description": "Office Supplies Purchase",
10       "debitAccountId": "acc_office_supplies",
11       "creditAccountId": "acc_bank",
12       "status": "PENDING",
13       "metadata": {
14         "receiptId": "R12345",
15         "vendor": "Office Depot"
16       },
17       "debitAccount": {
18         "id": "acc_office_supplies",
19         "name": "Office Supplies",
20         "type": "EXPENSE"
21       },
22       "creditAccount": {
23         "id": "acc_bank",
24         "name": "Bank Account",
25         "type": "ASSET"
26       }
27     }
28   ],
29   "nextCursor": "cursor_abc123",
30   "hasMore": true
31 }

Create a Transaction

Create a new transaction for an entity.

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

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity to create the transaction for

Request Body

Field	Type	Required	Description
`amount`	number	Yes	The amount of the transaction
`debitAccountId`	string	Yes	ID of the account to debit
`creditAccountId`	string	Yes	ID of the account to credit
`date`	string	No	When the transaction occurred (ISO 8601)
`currency`	string	No	Currency code (default: USD)
`description`	string	No	Description of the transaction
`status`	string	No	Transaction status (PENDING or CLEARED)
`metadata`	object	No	Additional metadata

1 {
2   "amount": 250.00,
3   "currency": "USD",
4   "description": "Office Supplies Purchase",
5   "debitAccountId": "acc_office_supplies",
6   "creditAccountId": "acc_bank",
7   "status": "PENDING",
8   "metadata": {
9     "receiptId": "R12345",
10     "vendor": "Office Depot"
11   }
12 }

Response

1 {
2   "transaction": {
3     "id": "txn_456def",
4     "entityId": "entity_012jkl",
5     "timestamp": "2023-05-15T14:22:00Z",
6     "amount": 250.00,
7     "currency": "USD",
8     "description": "Office Supplies Purchase",
9     "debitAccountId": "acc_office_supplies",
10     "creditAccountId": "acc_bank",
11     "status": "PENDING",
12     "metadata": {
13       "receiptId": "R12345",
14       "vendor": "Office Depot"
15     },
16     "createdAt": "2023-05-15T14:22:00Z",
17     "updatedAt": "2023-05-15T14:22:00Z"
18   }
19 }

Edit a Transaction

Edit an existing transaction by updating its accounts and/or description.

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

Request Body

Field	Type	Required	Description
`id`	string	Yes	The ID of the transaction to edit
`debit_account_id`	string	No	ID of the account to debit (optional if credit_account_id is provided)
`credit_account_id`	string	No	ID of the account to credit (optional if debit_account_id is provided)
`description`	string	No	New description for the transaction

1 {
2   "id": "txn_456def",
3   "debit_account_id": "acc_new_debit",
4   "credit_account_id": "acc_new_credit",
5   "description": "Updated Office Supplies Purchase"
6 }

Response

1 {
2   "id": "txn_456def",
3   "debit_account_id": "acc_new_debit",
4   "credit_account_id": "acc_new_credit",
5   "description": "Updated Office Supplies Purchase"
6 }

Approve Transactions

Approve one or multiple transactions by posting them to the ledger.

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

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity that owns the transactions

Request Body

The request body can be one of the following formats:

Single transaction ID as string:

1 "tx_1234567890abcdef"

Array of transaction IDs:

1 ["tx_1234567890abcdef", "tx_0987654321fedcba"]

Array of transaction objects:

1 [{"id": "tx_1234567890abcdef"}, {"id": "tx_0987654321fedcba"}]

Single transaction object:

1 {"id": "tx_1234567890abcdef"}

Response

1 {
2   "message": "Transactions approved successfully",
3   "approvedTransactions": [
4     {
5       "id": "tx_1234567890abcdef",
6       "status": "POSTED",
7       "updatedAt": "2023-05-15T16:45:22Z"
8     }
9   ]
10 }

Delete a Transaction

Delete an existing transaction.

1 DELETE /v1/transactions?entityId={entityId}&transactionId={transactionId}
2 Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity that owns the transaction
`transactionId`	string	The ID of the transaction to delete

Response

1 {
2   "message": "Transaction deleted successfully"
3 }

Get Transactions by Month

Retrieve transactions organized by month.

1 GET /v1/transactions/by-month?entityId={entityId}&month={month}&year={year}
2 Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity
`month`	integer	Month to filter by (1-12)
`year`	integer	Year to filter by
`cursor`	string	Cursor for pagination (optional)
`pageSize`	integer	Number of transactions per page (default: 50)

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     }
12   ],
13   "nextCursor": "cursor_def456",
14   "hasMore": false
15 }

Categorize a Transaction

Assign a category to a transaction.

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

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity that owns the transaction

Request Body

Field	Type	Required	Description
`transactionId`	string	Yes	The ID of the transaction to categorize
`categoryId`	string	Yes	The ID of the category to assign

1 {
2   "transactionId": "txn_456def",
3   "categoryId": "cat_123abc"
4 }

Response

1 {
2   "message": "Transaction categorized successfully",
3   "transaction": {
4     "id": "txn_456def",
5     "metadata": {
6       "categoryId": "cat_123abc",
7       "categoryName": "Office Supplies"
8     },
9     "updatedAt": "2023-05-15T16:55:30Z"
10   }
11 }

Search Transactions

Search for transactions using advanced criteria.

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

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity to search transactions for

Request Body

Field	Type	Description
`query`	string	Text to search in transaction descriptions
`filters`	object	Additional filters to apply
`page`	integer	Page number for pagination (default: 1)
`limit`	integer	Number of items per page (default: 20)

Filters object:

Field	Type	Description
`dateFrom`	string	Start date for filtering (YYYY-MM-DD)
`dateTo`	string	End date for filtering (YYYY-MM-DD)
`amountMin`	number	Minimum transaction amount
`amountMax`	number	Maximum transaction amount
`status`	string	Transaction status to filter by

1 {
2   "query": "office supplies",
3   "filters": {
4     "dateFrom": "2023-01-01",
5     "dateTo": "2023-06-30",
6     "amountMin": 100,
7     "amountMax": 500,
8     "status": "PENDING"
9   },
10   "page": 1,
11   "limit": 25
12 }

Response

1 {
2   "transactions": [
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       "debitAccountId": "acc_office_supplies",
10       "creditAccountId": "acc_bank",
11       "currency": "USD",
12       "metadata": {},
13       "createdAt": "2023-05-15T14:22:00Z",
14       "updatedAt": "2023-05-15T14:22:00Z"
15     }
16   ],
17   "pagination": {
18     "total": 12,
19     "page": 1,
20     "limit": 25,
21     "totalPages": 1
22   }
23 }

Transaction Chat

Get AI-assisted answers to questions about transactions.

1 GET /v1/transactions/chat?entityId={entityId}&prompt={query}
2 Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity
`prompt`	string	Natural language question about transactions

Response

1 {
2   "response": "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   "data": {
4     "transactions": [
5       {
6         "id": "txn_456def",
7         "description": "Office Supplies Purchase",
8         "amount": 250.00,
9         "timestamp": "2023-05-15T14:22:00Z"
10       }
11     ],
12     "summary": {
13       "total_amount": 3245.75,
14       "transaction_count": 8,
15       "average_amount": 405.72
16     }
17   }
18 }

Get Entity Counterparties

Get all counterparties for an entity with their transaction history.

1 GET /v1/transactions/counterparties?entityId={entityId}
2 Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`entityId`	string	The ID of the entity
`cursor`	string	Cursor for pagination (optional)
`pageSize`	integer	Number of counterparties per page (default: 50, max: 100)

Response

1 {
2   "success": true,
3   "counterparties": [
4     {
5       "name": "Office Depot",
6       "transactionCount": 15,
7       "firstSeen": "2023-01-15T12:00:00Z",
8       "lastSeen": "2023-05-15T14:22:00Z",
9       "totalAmount": 3750.25,
10       "averageAmount": 250.02
11     },
12     {
13       "name": "Amazon Business",
14       "transactionCount": 8,
15       "firstSeen": "2023-02-01T09:30:00Z",
16       "lastSeen": "2023-05-10T16:45:00Z",
17       "totalAmount": 1200.50,
18       "averageAmount": 150.06
19     }
20   ],
21   "nextCursor": "cursor_ghi789",
22   "hasMore": true
23 }

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

AI Analysis

AI-powered transaction categorization