POST
/transactions/batch Create multiple transactions in a batch
Create multiple transactions in a single API request. Each transaction is processed independently, supporting partial success. Maximum 100 transactions per batch (configurable). Searchable attributes are NOT supported on this endpoint: a batch item carrying attributes is rejected with 422 (attributes are immutable and write-once, so silently dropping them would be unrecoverable). Create attributed transactions via POST /api/v1/transactions.
Request bodyrequired
| Field | Type | Description |
|---|---|---|
transactionsrequired | object[] | Array of transactions to create (max 100) |
transactions[].idempotency_keyrequired | string | Unique key for idempotency (required per transaction). 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. |
transactions[].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. |
transactions[].descriptionrequired | string | |
transactions[].effective_daterequired | string 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. |
transactions[].layer | string enum: settled | pending | encumbrance · default: "settled" | Transaction HEADER layer — a header/filter value and the default for entries that don't declare their own layer; balance maths 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. |
transactions[].journal_id | string uuid · nullable | |
transactions[].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). |
transactions[].correlation_type | string max length: 50 · nullable | Correlation classifier (e.g. invoice, refund, reschedule). Paired with correlation_source_id: supply both or neither, or the whole batch is refused with 422. reversal, string_transfer and string_convert are reserved for the system: the whole batch is refused with 422. |
transactions[].correlation_source_id | string uuid · nullable | Optional predecessor transaction (same ledger) to link to, as on a single POST. Creates a Correlation pair row (source = this id, target = the new transaction) classified by correlation_type. A source not found in this ledger rejects the item with error_code validation_error; the other items are unaffected. |
transactions[].metadata | object nullable | |
transactions[].entriesrequired | object[] |
Responses
202Batch processed (may include partial success)
{
"success": true,
"data": {
"results": [
{
"idempotency_key": "resched-001",
"status": "accepted",
"id": "019bc5d1-8000-7c30-8d4e-5f6a7b8c9d0e",
"correlation_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"error": null,
"error_code": null
},
{
"idempotency_key": "resched-002",
"status": "rejected",
"id": null,
"correlation_id": null,
"error": "Source transaction not found in this ledger",
"error_code": "validation_error"
}
],
"summary": {
"total": 2,
"accepted": 1,
"rejected": 1
}
}
} 401Unauthenticated
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 403Forbidden
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 422Validation error (batch format invalid)
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 503Idempotency service unavailable (code SERVICE_UNAVAILABLE) — the whole batch is rejected 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/batch \
-H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
-H "Content-Type: application/json" \
-d '{
"transactions": [
{
"idempotency_key": "tx-001",
"reference": "INV-001",
"description": "Invoice payment",
"effective_date": "2026-01-15",
"entries": [
{
"account_code": "1000",
"type": "debit",
"amount": "100.00"
},
{
"account_code": "4000",
"type": "credit",
"amount": "100.00"
}
]
},
{
"idempotency_key": "tx-002",
"reference": "INV-002",
"description": "Second invoice payment",
"effective_date": "2026-01-15",
"entries": [
{
"account_code": "1000",
"type": "debit",
"amount": "200.00"
},
{
"account_code": "4000",
"type": "credit",
"amount": "200.00"
}
]
}
]
}' use Ledga\Api\LedgaClient;
$ledga = new LedgaClient('sk_xxxxxxxx_your_secret');
$result = $ledga->transactions->createBatch([
['idempotency_key' => 'tx-001', 'description' => 'Payment 1', 'effective_date' => '2026-01-15', 'entries' => [
['account_code' => '1000', 'type' => 'debit', 'amount' => '100.00'],
['account_code' => '4000', 'type' => 'credit', 'amount' => '100.00'],
]],
]);
echo "{$result->accepted}/{$result->total}";