> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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`
## OpenAPI
````yaml /openapi.yaml post /journal-entries
openapi: 3.1.0
info:
title: Arcus ERP Public API
version: 1.0.0
description: >
Arcus ERP public REST API. Designed for external integrations and data
migration.
**Authentication.** Bearer token (API key) via the `Authorization` header.
Format: `Authorization: Bearer ark_live_ent__` (or
`ark_test_*` for sandbox).
API keys are issued per-entity in **Settings > Developers > API Keys**.
**Entity scoping.** The entity is encoded in the API key prefix; routes are
flat
(e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform
endpoints
(migration, reconciliation, events, webhook endpoints, API keys) use the
`/v1/entities/{entity_id}/...` form -- those are noted in their tags.
**Key capabilities.**
- Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource).
- Cursor-based pagination (`starting_after` / `ending_before` / `limit`).
- Idempotency via the `Idempotency-Key` header.
- Webhook events for asynchronous notification.
- Conditional requests / ETag for cache validation.
servers:
- url: https://api.arcuserp.com/v1
description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys)
- url: https://dev-api.arcuserp.com/v1
description: >-
Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev
RDS)
security: []
paths:
/journal-entries:
post:
tags:
- Accounting
summary: Create a manual journal entry
description: >
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`
operationId: createJournalEntryV1
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- entry_date
- description
- lines
properties:
entry_date:
type: string
format: date
description: >
ISO date (YYYY-MM-DD). Must fall within an open accounting
period.
description:
type: string
source_type:
type: string
description: >
Source type label (defaults to MANUAL). Use canonical
JE_SOURCE_TYPE values when creating programmatic entries.
source_id:
type: string
description: UUID or reference of the source document
source_module:
type: string
lines:
type: array
minItems: 2
description: >
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.
items:
type: object
required:
- account_id
properties:
account_id:
type: string
format: uuid
debit:
type: number
minimum: 0
credit:
type: number
minimum: 0
description:
type: string
location_id:
type: string
format: uuid
department_id:
type: string
format: uuid
class_id:
type: string
format: uuid
project_id:
type: string
format: uuid
bypass_period_check:
type: boolean
description: >
Migration-only. Requires migration:write scope. Silently
dropped for all other callers. Every use is audit-logged.
default: false
responses:
'200':
description: Created journal entry (auto-approved or pending-approval)
content:
application/json:
schema:
$ref: '#/components/schemas/JournalEntry'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'403':
$ref: '#/components/responses/Error'
'409':
$ref: '#/components/responses/Error'
'422':
description: >
GL balance error (DR != CR), account postability error
(header/inactive account), or period closed. See error.code for
detail: gl_imbalance | account_is_header | account_inactive |
account_not_found | period_closed | line_has_both_debit_and_credit.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKeyAuth: []
components:
schemas:
JournalEntry:
type: object
description: >
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.
properties:
id:
type: string
format: uuid
readOnly: true
entity_id:
type: string
format: uuid
readOnly: true
entry_number:
type: string
readOnly: true
description: Human-readable number (e.g. SB-JE-0000001)
entry_date:
type: string
format: date
period_id:
type: string
format: uuid
nullable: true
readOnly: true
entry_type:
type: string
nullable: true
status:
type: string
enum:
- draft
- pending_approval
- posted
- reversed
- voided
- rejected
readOnly: true
approval_status:
type: string
enum:
- auto_approved
- pending_approval
- approved
- rejected
nullable: true
readOnly: true
description:
type: string
source_type:
type: string
description: >
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`.
enum:
- INVOICE
- FULFILLMENT
- TAX
- SHIPPING
- SHIPPING_COST
- DISCOUNT
- PRICING_DISCOUNT
- COUPON_DISCOUNT
- PROCESSING_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:
type: string
nullable: true
source_module:
type: string
nullable: true
is_reversing:
type: boolean
readOnly: true
reversed_by_id:
type: string
format: uuid
nullable: true
readOnly: true
reversal_of_id:
type: string
format: uuid
nullable: true
readOnly: true
reverse_in_period_id:
type: string
format: uuid
nullable: true
readOnly: true
batch_id:
type: string
format: uuid
nullable: true
description: >
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:
type: number
readOnly: true
total_credit:
type: number
readOnly: true
posted_at:
type: string
format: date-time
nullable: true
readOnly: true
approved_by:
type: string
format: uuid
nullable: true
readOnly: true
approved_at:
type: string
format: date-time
nullable: true
readOnly: true
rejected_by:
type: string
format: uuid
nullable: true
readOnly: true
rejected_at:
type: string
format: date-time
nullable: true
readOnly: true
rejection_reason:
type: string
nullable: true
readOnly: true
idempotency_key:
type: string
nullable: true
created_by:
type: string
format: uuid
nullable: true
readOnly: true
description: >-
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:
type: string
nullable: true
readOnly: true
description: >-
Display name of the creating user (JOIN on users). Null for
system-generated entries with no user attribution.
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
lines:
type: array
readOnly: true
description: JE lines (included on GET single; omitted on list responses)
items:
$ref: '#/components/schemas/JournalEntryLine'
Error:
description: |
Alias for ErrorEnvelope. Canonical error response shape used by all
API endpoints. Refer to ErrorEnvelope for the full field definition.
allOf:
- $ref: '#/components/schemas/ErrorEnvelope'
JournalEntryLine:
type: object
description: >
A single debit or credit line within a journal entry. Exactly one of
debit_amount or credit_amount is > 0. account_id must reference a
postable leaf account (Rule A2). Verified against live dev RDS
accounting.journal_entry_lines.
properties:
id:
type: string
format: uuid
readOnly: true
journal_entry_id:
type: string
format: uuid
readOnly: true
line_number:
type: integer
readOnly: true
account_id:
type: string
format: uuid
debit_amount:
type: number
minimum: 0
description: Debit amount (0 if credit line)
credit_amount:
type: number
minimum: 0
description: Credit amount (0 if debit line)
description:
type: string
nullable: true
location_id:
type: string
format: uuid
nullable: true
department_id:
type: string
format: uuid
nullable: true
class_id:
type: string
format: uuid
nullable: true
project_id:
type: string
format: uuid
nullable: true
reconciled:
type: boolean
readOnly: true
reconciled_at:
type: string
format: date-time
nullable: true
readOnly: true
created_at:
type: string
format: date-time
readOnly: true
ErrorEnvelope:
type: object
description: |
Canonical error response envelope. All API errors use this shape.
required:
- error
- code
properties:
error:
type: string
description: Machine-readable error key
example: not_found
code:
type: string
description: Machine-readable error code (often same as error)
example: not_found
type:
type: string
enum:
- validation_error
- permission_error
- not_found
- conflict
- rate_limit
- internal
- expand_error
- not_implemented
example: not_found
hint:
type: string
description: Human-readable one-sentence explanation (English)
example: >-
The requested order does not exist or does not belong to this
entity.
param:
type: string
description: The parameter that caused the error, if applicable
example: expand[0]
required:
type: string
description: The scope required (only on insufficient_scope errors)
example: accounts:read
request_id:
type: string
description: >-
Unique request ID for support tracing (maps to CloudWatch log
stream)
example: req_abc123
responses:
Error:
description: Error response (400/401/403/404/409/422/429/500)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: |
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.
````