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
`transactions`required	object[]	Array of transactions to create (max 100)
`transactions[].idempotency_key`required	string	Unique key for idempotency (required per transaction)
`transactions[].reference`	string	External reference number
`transactions[].description`required	string
`transactions[].effective_date`required	string date
`transactions[].layer`	string enum: settled \| pending \| encumbrance · default: "settled"	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 nullable
`transactions[].metadata`	object nullable
`transactions[].entries`required	object[]

Responses

202Batch processed (may include partial success)

{
  "success": true,
  "data": {
    "results": [
      {
        "idempotency_key": "string",
        "status": "accepted"
      }
    ],
    "summary": {
      "total": 0,
      "accepted": 0,
      "rejected": 0
    }
  }
}

400Validation error (batch format invalid)

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}

401Unauthenticated

{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}

403Forbidden

{
  "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",
      "layer": "settled",
      "entries": [
        {
          "account_code": "1000",
          "account_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
          "type": "debit",
          "amount": "100.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}";

← All endpoints