Ledga

Transactions

Balanced, immutable postings. Create them from explicit entries or by invoking a transaction code.

Endpoints

MethodPathDescription
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" }
    ]
  }'

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" }
  }'

Lifecycle

  • POST writes the transaction, then returns 202 with status: "pending"; GET /transactions/{id} shows posted. Other statuses: reversed, void, draft.
  • 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.
  • Search: GET /transactions/by-attribute?key=customer_id&value=C-123 finds 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" }
    ]
  }'

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_id takes the source’s handle, so one handle finds both. Above, the source had no correlation_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_id you send wins. The source’s handle then does not find the new transaction. correlation_id is at most 50 characters.

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.