# Create Journal Entry

Create a new journal entry with lines.

Double-Entry Rule: Sum of debits MUST equal sum of credits.
The entry will be rejected if not balanced.

Immutability: Journal entries are immutable once created.
Use adjustment entries for corrections.

Account Codes:
- REVENUE - Revenue accounts
- AR - Accounts Receivable
- CONTRA_REVENUE - Contra-revenue (discounts)
- CLEARING - Clearing accounts
- BANK - Bank accounts
- FEE_EXPENSE - Processing fee expenses
- REFUND_EXPENSE - Refund expenses

Endpoint: POST /ledger/journalEntries
Version: 1.0.0
Security: OAuth2

## Header parameters:

  - `Idempotency-Key` (string)
    Unique key to ensure idempotent operations (UUID recommended)

## Request fields (application/json):

  - `entryDate` (string, required)

  - `currency` (string)

  - `source` (string, required)
    Source of journal entry
    Enum: "INVOICE", "PAYMENT", "REFUND", "ADJUSTMENT", "REMITTANCE"

  - `sourceReference` (string)

  - `adjustmentType` (string)
    Type of adjustment for manual entries
    Enum: "STANDARD", "DISCOUNT_CORRECTION", "FEE_CORRECTION", "CREDIT_MEMO", "DEBIT_MEMO", "WRITE_OFF"

  - `reason` (string)

  - `relatedSourceRef` (string)

  - `lines` (array, required)

  - `lines.accountCode` (string, required)
    Chart of accounts code
    Enum: "REVENUE", "AR", "CONTRA_REVENUE", "CLEARING", "BANK", "FEE_EXPENSE", "REFUND_EXPENSE"

  - `lines.externalAccountCode` (string)

  - `lines.direction` (string, required)
    Direction of journal line
    Enum: "DEBIT", "CREDIT"

  - `lines.amount` (integer, required)

  - `lines.description` (string)

  - `lines.billableEntityId` (string)

  - `lines.accountId` (string)

  - `lines.invoiceId` (string)

  - `lines.dimensions` (object)

  - `lines.tags` (object)

## Response 201 fields (application/json):

  - `id` (string, required)

  - `entityId` (string, required)

  - `entryDate` (string, required)

  - `currency` (string, required)
    ISO 4217 currency code

  - `source` (string, required)
    Source of journal entry
    Enum: "INVOICE", "PAYMENT", "REFUND", "ADJUSTMENT", "REMITTANCE"

  - `sourceReference` (string)
    Reference to source document (e.g., invoice ID)

  - `references` (object)
    Nested map of invoice IDs to charge IDs for tracing.
Structure: { "invoiceId": ["chargeId1", "chargeId2"], ... }
Enables tracking when a payment applies to multiple invoices.

  - `adjustmentType` (string)
    Type of adjustment for manual entries
    Enum: "STANDARD", "DISCOUNT_CORRECTION", "FEE_CORRECTION", "CREDIT_MEMO", "DEBIT_MEMO", "WRITE_OFF"

  - `reason` (string)
    Reason for adjustment (if applicable)

  - `adminUserId` (string)
    Admin user who created the entry (for adjustments)

  - `relatedSourceRef` (string)
    Reference to related entries

  - `totalAmount` (integer, required)
    Total amount of the entry in cents

  - `isBalanced` (boolean, required)
    Whether debits equal credits

  - `lines` (array, required)

  - `lines.accountCode` (string, required)
    Chart of accounts code
    Enum: "REVENUE", "AR", "CONTRA_REVENUE", "CLEARING", "BANK", "FEE_EXPENSE", "REFUND_EXPENSE"

  - `lines.externalAccountCode` (string)
    External GL account code for export

  - `lines.direction` (string, required)
    Direction of journal line
    Enum: "DEBIT", "CREDIT"

  - `lines.amount` (integer, required)
    Amount in cents (always positive)

  - `lines.description` (string)

  - `lines.billableEntityId` (string)

  - `lines.accountId` (string)

  - `lines.invoiceId` (string)

  - `lines.dimensions` (object)
    Reporting dimensions

  - `lines.tags` (object)

  - `optimisticLockVersion` (integer)
    Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

  - `createdAt` (string, required)

## Response 400 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]

## Response 401 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]