Transactions
Balanced, immutable postings. Create them from explicit entries or by invoking a transaction code.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /transactions | List all transactions in a ledger |
| POST | /transactions | Create a new transaction (direct entries or trancode invocation) |
| GET | /transactions/correlation | List transactions sharing a correlation ID (chronological) |
| GET | /transactions/by-attribute | Search transactions by a searchable business dimension (tenant-scoped, cross-ledger) |
| POST | /transactions/search | Search the ledger's transactions by their attributes |
| POST | /transactions/search/totals | Count and sum the transactions a filter matches |
| POST | /transactions/search/export | Export the transactions a filter matches |
| POST | /transactions/batch | Create multiple transactions in a batch |
| GET | /transactions/{transactionId} | Get a specific transaction |
| GET | /transactions/{transactionId}/status | Get a transaction's verification status |
| POST | /transactions/{transactionId}/reverse | Reverse a posted transaction |
| POST | /transactions/{transactionId}/void | Void a posted transaction |
Direct entries
Supply entries[]. Debits must equal credits; idempotency_key is required.
curl -X POST https://ledga.io/api/v1/transactions \
-H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
-H "Content-Type: application/json" \
-d '{
"effective_date": "2026-01-15",
"description": "Invoice INV-001 paid",
"reference": "INV-001",
"layer": "settled",
"idempotency_key": "inv-001-payment",
"entries": [
{ "account_code": "1000", "type": "debit", "amount": "500.00" },
{ "account_code": "4000", "type": "credit", "amount": "500.00" }
]
}'$ack = $ledga->transactions->create([
'effective_date' => '2026-01-15',
'description' => 'Invoice INV-001 paid',
'reference' => 'INV-001',
'layer' => 'settled',
'idempotency_key' => 'inv-001-payment',
'entries' => [
['account_code' => '1000', 'type' => 'debit', 'amount' => '500.00'],
['account_code' => '4000', 'type' => 'credit', 'amount' => '500.00'],
],
]);Invoke a transaction code
Supply transaction_code and transaction_code_params instead of entries. Sending both returns 422.
curl -X POST https://ledga.io/api/v1/transactions \
-H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
-H "Content-Type: application/json" \
-d '{
"effective_date": "2026-01-15",
"description": "Customer payment",
"idempotency_key": "cp-001",
"transaction_code": "BOOK_TRANSFER",
"transaction_code_params": { "amount": "100.00", "from_account": "1000", "to_account": "4000" }
}'$ack = $ledga->transactions->createFromCode(
'BOOK_TRANSFER',
['amount' => '100.00', 'from_account' => '1000', 'to_account' => '4000'],
['description' => 'Customer payment', 'effective_date' => '2026-01-15', 'idempotency_key' => 'cp-001'],
);Lifecycle
POSTwrites the transaction, then returns202withstatus: "pending";GET /transactions/{id}showsposted. Other statuses:reversed,void,draft.- Reverse:
POST /transactions/{id}/reversewithreasonanddateposts an equal and opposite transaction. - Void:
POST /transactions/{id}/voidmarks itvoidand recalculates balances; entries are untouched. - Batch:
POST /transactions/batchtakes up to 100 items, each processed independently (partial success).attributesare not accepted on batch items. - Search:
GET /transactions/by-attribute?key=customer_id&value=C-123finds postings by a declared attribute.
Transactions have no PUT or DELETE.
Correlating transactions
Link a transaction to the one it follows with correlation_source_id and correlation_type. Send both or neither: either one alone is a 422. The source must be a transaction in the same ledger. reversal, string_transfer and string_convert are reserved for the API’s own links, so a correlation_type of any of them is a 422. To label a transaction without linking it, use attributes.
curl -X POST https://ledga.io/api/v1/transactions \
-H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
-H "Content-Type: application/json" \
-d '{
"effective_date": "2026-02-15",
"description": "Replacement encumbrance",
"layer": "encumbrance",
"idempotency_key": "resched-001",
"correlation_source_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"correlation_type": "reschedule",
"entries": [
{ "account_code": "1300", "type": "debit", "amount": "250.00" },
{ "account_code": "4000", "type": "credit", "amount": "250.00" }
]
}'$ack = $ledga->transactions->create([
'effective_date' => '2026-02-15',
'description' => 'Replacement encumbrance',
'layer' => 'encumbrance',
'idempotency_key' => 'resched-001',
'correlation_source_id' => '01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a',
'correlation_type' => 'reschedule',
'entries' => [
['account_code' => '1300', 'type' => 'debit', 'amount' => '250.00'],
['account_code' => '4000', 'type' => 'credit', 'amount' => '250.00'],
],
]);The handle
Every transaction has a correlation handle: its correlation_id, or its own id when it has none. The 202 returns the handle as correlation_id, and the handle always finds the transaction.
-
A transaction that names a source but sends no
correlation_idtakes the source’s handle, so one handle finds both. Above, the source had nocorrelation_id, so the handle is the source’s id:{ "success": true, "data": { "id": "01997c2f-8b1d-7a40-b2c6-5e9d0f1a3c7e", "status": "pending", "idempotency_key": "resched-001", "correlation_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a", "message": "Transaction accepted and processing" } } -
A
correlation_idyou send wins. The source’s handle then does not find the new transaction.correlation_idis at most 50 characters.
Reading links
Every transaction payload carries correlation_id (the handle, never null), correlation_source_id and correlation_type. The two link fields are both set or both null. A reversal reads its original, with correlation_type reversal.
The trail
GET /transactions/correlation?correlation_id={handle} returns every transaction with a handle, oldest first (posting order); in PHP, byCorrelation() or allByCorrelation(). An unknown handle returns an empty page, not 404. GET /transactions?correlation_id= and a search filter’s correlation_id match the same transactions, in their own order.
The handle is a query parameter, so URL-encode it. A handle over 50 characters, not valid UTF-8, or holding a NUL is a 422.
Batches
POST /transactions/batch items take the same three fields, with the same pairing. A lone correlation_source_id or correlation_type, or a reserved correlation_type, on any item refuses the whole batch with 422. A source not found in the ledger rejects only that item, with error_code validation_error. An item cannot link to a transaction created in the same batch.