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/batch`	Create multiple transactions in a batch
GET	`/transactions/{transactionId}`	Get a specific transaction
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

POST returns 202 with status: "pending"; GET /transactions/{id} shows posted once written. Other statuses: failed, reversed, void.
Reverse: POST /transactions/{id}/reverse with reason and date posts an equal and opposite transaction.
Void: POST /transactions/{id}/void marks it void and recalculates balances; entries are untouched.
Batch: POST /transactions/batch takes up to 100 items, each processed independently (partial success). attributes are not accepted on batch items.
Correlate: set correlation_id (and correlation_type) to group postings; GET /transactions/correlation?correlation_id=… returns the trail in posting order.
Search: GET /transactions/by-attribute?key=customer_id&value=C-123 finds postings by a declared attribute.

Transactions have no PUT or DELETE.