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
| Field | Type | Description |
|---|---|---|
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"
}
]
}' use Ledga\Api\LedgaClient;
$ledga = new LedgaClient('sk_xxxxxxxx_your_secret');
$ack = $ledga->transactions->create([
'effective_date' => '2026-01-15',
'description' => 'Invoice INV-001 paid',
'idempotency_key' => 'inv-001-payment',
'entries' => [
['account_code' => '1000', 'type' => 'debit', 'amount' => '500.00'],
['account_code' => '4000', 'type' => 'credit', 'amount' => '500.00'],
],
]);
$transaction = $ledga->transactions->get($ack->id);