Create a manual journal entry

Required API key scope: accounting:write

Creates a manual journal entry. The entry is subject to the entity’s approval workflow thresholds (je_approval_threshold_low / _high). Entries at or below the low threshold are auto-approved. Above the high threshold require manager or owner approval.

Invariants enforced (all P0):

• DR sum = CR sum (assertGLBalance, Rule A1). Returns 422 on imbalance.
• Every line targets a postable leaf account (assertGLLinesPostable, Rule A2). Returns 422 if any line references a header or inactive account.
• Entry date must fall within an OPEN accounting period (Rule A3). Returns 422 with code period_closed if the period is closed.
• No line may have both debit > 0 AND credit > 0.

Use bypass_period_check=true only with a migration:write scoped key (WSS migration backfill). Every gated use is audit-logged.

Supports Idempotency-Key header for safe retries.

Expand paths: lines, lines.gl_account

POST /journal-entries

Create a manual journal entry

cURL

curl --request POST \
  --url https://api.arcuserp.com/v1/journal-entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entry_date": "2023-12-25",
  "description": "<string>",
  "lines": [
    {
      "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "debit": 1,
      "credit": 1,
      "description": "<string>",
      "location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "department_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "class_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "source_type": "<string>",
  "source_id": "<string>",
  "source_module": "<string>",
  "bypass_period_check": false
}
'

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entry_number": "<string>",
  "entry_date": "2023-12-25",
  "period_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entry_type": "<string>",
  "status": "draft",
  "approval_status": "auto_approved",
  "description": "<string>",
  "source_type": "INVOICE",
  "source_id": "<string>",
  "source_module": "<string>",
  "is_reversing": true,
  "reversed_by_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reversal_of_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reverse_in_period_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "batch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "total_debit": 123,
  "total_credit": 123,
  "posted_at": "2023-11-07T05:31:56Z",
  "approved_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "approved_at": "2023-11-07T05:31:56Z",
  "rejected_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rejected_at": "2023-11-07T05:31:56Z",
  "rejection_reason": "<string>",
  "idempotency_key": "<string>",
  "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_by_name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "lines": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "journal_entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "line_number": 123,
      "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "debit_amount": 1,
      "credit_amount": 1,
      "description": "<string>",
      "location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "department_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "class_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "reconciled": true,
      "reconciled_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization · string · header · required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.

Body

application/json

entry_date · string<date> · required

ISO date (YYYY-MM-DD). Must fall within an open accounting period.

description · string · required

lines · object[] · required

Journal entry lines. Every line must reference a postable (non-header, active, entity-scoped) GL account. Exactly one of debit or credit must be > 0 per line. DR sum must equal CR sum across all lines.

Minimum array length: 2

Show child attributes

source_type · string

Source type label (defaults to MANUAL). Use canonical JE_SOURCE_TYPE values when creating programmatic entries.

source_id · string

UUID or reference of the source document

source_module · string

bypass_period_check · boolean · default: false

Migration-only. Requires migration:write scope. Silently dropped for all other callers. Every use is audit-logged.

Response

200

application/json

Created journal entry (auto-approved or pending-approval)

A double-entry journal entry. DR sum = CR sum across all lines (Rule A1 / assertGLBalance). entry_date must fall in an open accounting period (Rule A3). Once posted, entries are immutable -- use reverse to undo. Verified against live dev RDS accounting.journal_entries.

id · string<uuid> · read-only

entity_id · string<uuid> · read-only

entry_number · string · read-only

Human-readable number (e.g. SB-JE-0000001)

entry_date · string<date>

period_id · string<uuid> | null · read-only

entry_type · string | null

status · enum<string> · read-only

Available options: draft, pending_approval, posted, reversed, voided, rejected

approval_status · enum<string> | null · read-only

Available options: auto_approved, pending_approval, approved, rejected

description · string

source_type · enum<string>

Event source. Postgres ENUM-locked per P0-JE-SOURCE-TYPE-ENUM (2026-05-18, FIX REQUIRED #18 closed). Invalid values rejected with HTTP 400 at the API boundary and Postgres 22P02 at the database layer. Values mirror JE_SOURCE_TYPE in arcus-api-core/utils/constants.mjs.

Available options: INVOICE, FULFILLMENT, TAX, SHIPPING, SHIPPING_COST, DISCOUNT, PRICING_DISCOUNT, COUPON_DISCOUNT, PROCESSING_FEE, PROCESSOR_FEE, ORDER_CANCELLATION, LATE_FEE, PAYMENT, REFUND, CREDIT_APPLIED, WRITE_OFF, CREDIT_MEMO, CUSTOMER_DEPOSIT, CUSTOMER_DEPOSIT_APPLICATION, CUSTOMER_DEPOSIT_REFUND, RETURN, RETURN_FEE, COGS_REVERSAL, VENDOR_RETURN, AP_BILL, AP_PAYMENT, VENDOR_BILL, VENDOR_INVOICE, VENDOR_PAYMENT, VENDOR_CREDIT, BILL_REVALUATION, VENDOR_PREPAYMENT, VENDOR_PREPAYMENT_APPLICATION, VENDOR_PREPAYMENT_REFUND, INVENTORY_ADJUSTMENT, INVENTORY_ADJ, INVENTORY_RECEIVED, INVENTORY_TRANSFER, INTERCOMPANY_TRANSFER, CYCLE_COUNT, PO_RECEIPT, PO_DAMAGED_WRITEOFF, COST_REVALUATION, BANK_RECON, BANK_DEPOSIT, CASH_MOVEMENT, CHECK_CLEARED, PAYOUT, REGISTER, REGISTER_SALE, SHOPIFY_IMPORT, SHOPIFY_PAYOUT, AMAZON_IMPORT, AMAZON_SETTLEMENT, EBAY_IMPORT, EBAY_PAYOUT, MARKETPLACE_PAYOUT, AMAZON_FEES, FBA_INBOUND, FBA_SYNC, TAX_REMITTANCE, DISPUTE_HOLD, DISPUTE_WON, DISPUTE_LOST, MANUAL, MANUAL_REVERSAL, PERIOD_CLOSE, FISCAL_YEAR_CLOSE, ADJUSTMENT, RECURRING_JE, MANUFACTURING, WO_COMPLETION, WO_VARIANCE, WO_LABOR, WO_OVERHEAD, DEPRECIATION, ASSET_ACQUISITION, ASSET_DISPOSAL, IMPAIRMENT, LEASE_COMMENCEMENT, LEASE_PAYMENT, LEASE_MODIFICATION, LEASE_TERMINATION, LEASE_BUYOUT, LABEL_REFUND_DENIED

source_id · string | null

source_module · string | null

is_reversing · boolean · read-only

reversed_by_id · string<uuid> | null · read-only

reversal_of_id · string<uuid> | null · read-only

reverse_in_period_id · string<uuid> | null · read-only

batch_id · string<uuid> | null

Groups JEs from one business event (e.g. fulfillment posts revenue + COGS + tax + shipping in one batch). Use GET /v1/journal-entries?batch_id= to retrieve all JEs in a batch.

total_debit · number · read-only

total_credit · number · read-only

posted_at · string<date-time> | null · read-only

approved_by · string<uuid> | null · read-only

approved_at · string<date-time> | null · read-only

rejected_by · string<uuid> | null · read-only

rejected_at · string<date-time> | null · read-only

rejection_reason · string | null · read-only

idempotency_key · string | null

created_by · string<uuid> | null · read-only

User who created the entry. Stamped from the authenticated user on manual JEs; from the posting helper's created_by on system JEs.

created_by_name · string | null · read-only

Display name of the creating user (JOIN on users). Null for system-generated entries with no user attribution.

created_at · string<date-time> · read-only

updated_at · string<date-time> · read-only

lines · object[] · read-only

JE lines (included on GET single; omitted on list responses)

Show child attributes