Ledga
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

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

← All endpoints