Ledga
POST /transactions

Create a new transaction (direct entries or trancode invocation)

Two mutually exclusive modes. Direct: supply entries[]. Template: supply transaction_code and transaction_code_params; the server validates the params against the code's params_schema and materialises its entries. Sending both returns 422. The transaction is written before the 202 acknowledgement returns; only its verification is asynchronous (GET /api/v1/transactions/{transactionId}/status). A retry with the same idempotency_key returns that acknowledgement again, with 200.

Request bodyrequired

FieldTypeDescription
effective_daterequired string
date
Transaction effective date. A bare date (YYYY-MM-DD) is the start of that day in the ledger's timezone; a date-time with no offset is wall-clock time in the ledger's timezone; a date-time with an offset or Z is that instant. At most 30 days ahead (to the end of the ledger's day), unless the header and every entry are on the encumbrance layer; otherwise a 422.
descriptionrequired string
reference string External reference number. Not in the shape a period close writes, CLOSE-<monthly|quarterly|yearly>-<period end> with -2, -3 and so on, which is reserved for it.
layer string
enum: settled | pending | encumbrance · default: "settled"
Transaction HEADER layer — a header/filter value (it is what GET /transactions?layer= matches) and the default for entries that don't declare their own layer. It is NOT authoritative for balance maths: every layered-balance query reads entries.layer. Case-insensitive on the request side; values like Settled or SETTLED are normalised to canonical lowercase before validation. Responses always render the canonical lowercase form.
journal_id string
uuid · nullable
correlation_id string
max length: 50 · nullable
Group related transactions. If omitted but correlation_source_id is given, defaults to the source transaction's group handle (its correlation_id, else its id).
correlation_type string
max length: 50 · nullable
Correlation classifier (e.g. invoice, refund, reschedule). Paired with correlation_source_id — supply both or neither. reversal, string_transfer and string_convert are reserved for the system: 422.
correlation_source_id string
uuid · nullable
Optional predecessor transaction (same ledger) to link to. Creates a Correlation pair row (source = this id, target = the new transaction) classified by correlation_type — e.g. a reschedule replacement pointing at its voided original. A source with no correlation_id is given its own id as its handle, never this transaction's correlation_id.
idempotency_keyrequired string Unique key to prevent duplicate transactions. Not in the shape a period close writes, period_close_<ledger id>_<period end> with _2, _3 and so on, which is reserved for it.
metadata object
nullable
attributes object
nullable
Optional searchable business dimensions — a flat map of key => value string pairs (e.g. {"customer_id": "C-123", "loan_id": "L-42"}). Applies to both posting modes. Keys must be lowercase snake_case (max 64 chars) and not shadow a reserved field; values are strings (max 128 chars). Subject to per-transaction (default 20) and per-tenant distinct-key caps, and, when the tenant runs strict mode, must be declared in the attribute catalog first — a violation returns 422 with an ATTRIBUTE_* code. Written atomically with the transaction and immutable thereafter.
entries object[] Direct mode only. Double-entry transaction entries (must balance after server-side resolution). Mutually exclusive with transaction_code.
entries[].account_code string Account code (alternative to account_id)
entries[].account_id string
uuid
Account UUID (alternative to account_code)
entries[].typerequired string
enum: debit | credit
entries[].amountrequired string Amount in major units (e.g., dollars)
entries[].description string
nullable
entries[].metadata object
nullable
entries[].layer string
enum: settled | pending | encumbrance · nullable
Layer this entry posts to. Optional — falls back to the transaction-level layer, then settled. Entries within one transaction MAY differ: a layer transition is posted as a single balanced transaction carrying a contra pair in the source layer plus a fresh pair in the target layer. This value is authoritative for balance maths (every layered-balance query reads the entry layer); the transaction-level layer is a header/filter value. Case-insensitive; an unrecognised value is a 422, never a silent fallback.
transaction_code string
max length: 50
Template mode only. Code of an active trancode in this ledger. Must be paired with transaction_code_params. Mutually exclusive with entries.
transaction_code_params object Template mode only. Parameter map keyed by parameter name as declared in the trancode's params_schema. Values are substituted into the template (account selectors and amount expressions) at materialisation time.

Responses

200Replay of an earlier request with this idempotency_key and the same body: its original acknowledgement, with meta.replayed: true
{
  "success": true,
  "meta": {
    "replayed": true
  },
  "data": {
    "id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
    "status": "pending",
    "idempotency_key": "payment-inv-2025-001",
    "correlation_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
    "message": "Transaction accepted and processing"
  }
}
202Transaction accepted and processing
{
  "success": true,
  "data": {
    "id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
    "status": "pending",
    "idempotency_key": "payment-inv-2025-001",
    "correlation_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
    "message": "Transaction accepted and processing"
  }
}
401Unauthenticated
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
403Forbidden
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
409The idempotency key is taken: idempotency_key_reused (used with another body, by a reversal, or by another writer), or idempotency_key_in_use / idempotency_lock_failed (a request with it is in flight; retry). Or the effective date falls in a closed period or one whose close is in progress (code PERIOD_LOCKED). Nothing is written
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
422Validation error, a balance limit would be breached (code BALANCE_LIMIT_EXCEEDED), or an account was deleted while posting (code ACCOUNT_DELETED); either names the account in errors.account_code
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
503Idempotency service unavailable (code SERVICE_UNAVAILABLE) — fail-closed with a Retry-After header; nothing is written
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}

Examples

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",
  "idempotency_key": "inv-001-payment",
  "entries": [
    {
      "account_code": "1000",
      "type": "debit",
      "amount": "500.00"
    },
    {
      "account_code": "4000",
      "type": "credit",
      "amount": "500.00"
    }
  ]
}'

← All endpoints