Journal Entries and Period Close

What this guide covers

This guide walks through two closely related tasks:

Manual journal entries — posting adjusting, accrual, or correcting entries with balanced lines
Period close — locking a period after all entries are in so no accidental postings slip through

Most GL entries are posted automatically by Arcus when business events occur (order fulfillment, payments, receipts). Manual JEs are for adjusting entries, accruals, depreciation, and corrections that do not originate from a transaction.

Prerequisites

API key with scope accounting:write (create JEs)
API key with scope accounting:approve (approve JEs above threshold)
API key with scope accounting:close_period (close and reopen periods)
API key with scopes accounting:close_period and accounting:approve (approve another user’s close request)
The user who created each API key must also hold the matching permission in their role; the key acts as that user, and a missing permission returns 403 permission_denied on reversals and period calls
Valid account_id values for postable GL accounts (use GET /v1/gl-accounts?postable_only=true)
An open accounting period that covers your entry_date

The two non-negotiable rules

Before writing any JE code, understand the two rules Arcus enforces at every write path:

1. Debits must equal credits

Every journal entry must balance: the sum of all debit amounts must equal the sum of all credit amounts. An off-by-one-cent imbalance is a validation failure.

Rule: SUM(debit) == SUM(credit)

If the amounts do not balance, the API returns 422 with code: gl_imbalance and includes the exact difference:

{
  "error": "gl_imbalance",
  "code": "gl_imbalance",
  "type": "validation_error",
  "hint": "GL posting imbalance [MANUAL]: debits=500.00 credits=300.00 diff=200.0000"
}

2. Post to leaf accounts only

You cannot post to header (rollup) accounts like “1000 Cash and Bank Accounts” or “1400 Inventory.” You must post to a leaf account like “1011 Operating Checking” or “1410 Finished Goods Inventory.” Use GET /v1/gl-accounts?postable_only=true to get the list of valid accounts for your entity.

{
  "error": "account_is_header",
  "code": "account_is_header",
  "type": "validation_error",
  "hint": "GL account 1000 is a header account and cannot be posted to directly.",
  "param": "lines[0].account_id"
}

Posting a manual journal entry

Example: prepaid insurance amortization

1,200 annual insurance policy paid upfront. Each month,

100 moves from Prepaid Expenses to Insurance Expense.

curl -s -X POST "https://api.arcuserp.com/v1/journal-entries" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: je-insurance-amort-2026-05" \
  -d '{
    "entry_date": "2026-05-31",
    "description": "Prepaid insurance amortization - May 2026",
    "lines": [
      {
        "account_id": "gl_insurance_expense_uuid",
        "debit": 100.00,
        "description": "Insurance expense May"
      },
      {
        "account_id": "gl_prepaid_expenses_uuid",
        "credit": 100.00,
        "description": "Release prepaid"
      }
    ]
  }'

import Arcus from "@arcuserp/sdk";

const arcus = new Arcus({ apiKey: process.env.ARCUS_API_KEY });

const je = await arcus.journalEntries.create({
  entry_date: "2026-05-31",
  description: "Prepaid insurance amortization - May 2026",
  lines: [
    {
      account_id: "gl_insurance_expense_uuid",
      debit: 100.00,
      description: "Insurance expense May",
    },
    {
      account_id: "gl_prepaid_expenses_uuid",
      credit: 100.00,
      description: "Release prepaid",
    },
  ],
}, { headers: { "Idempotency-Key": "je-insurance-amort-2026-05" } });

console.log(je.data.id);     // je_uuid
console.log(je.data.status); // posted (or pending_approval if above threshold)
console.log(je.data.entry_number); // JE-00128

import arcuserp, os

client = arcuserp.Arcus(api_key=os.environ["ARCUS_API_KEY"])

je = client.journal_entries.create(
    entry_date="2026-05-31",
    description="Prepaid insurance amortization - May 2026",
    lines=[
        {
            "account_id": "gl_insurance_expense_uuid",
            "debit": 100.00,
            "description": "Insurance expense May",
        },
        {
            "account_id": "gl_prepaid_expenses_uuid",
            "credit": 100.00,
            "description": "Release prepaid",
        },
    ],
    extra_headers={"Idempotency-Key": "je-insurance-amort-2026-05"},
)

print(je.data.id)
print(je.data.status)  # posted or pending_approval

Response shape

{
  "data": {
    "id": "je_uuid_abc",
    "entry_number": "JE-00128",
    "entry_date": "2026-05-31",
    "description": "Prepaid insurance amortization - May 2026",
    "status": "posted",
    "total_debit": 100.00,
    "total_credit": 100.00,
    "source_type": "MANUAL",
    "lines": [
      {
        "id": "jel_uuid_1",
        "account_id": "gl_insurance_expense_uuid",
        "line_number": 1,
        "debit_amount": 100.00,
        "credit_amount": 0.00,
        "description": "Insurance expense May"
      },
      {
        "id": "jel_uuid_2",
        "account_id": "gl_prepaid_expenses_uuid",
        "line_number": 2,
        "debit_amount": 0.00,
        "credit_amount": 100.00,
        "description": "Release prepaid"
      }
    ]
  }
}

Lines are sent as debit and credit, and come back as debit_amount and credit_amount. The body also takes optional source_type (defaults to MANUAL), source_id and source_module, and per line an optional description, location_id, department_id, class_id and project_id.

The posting window

Besides an open period, the entry_date must sit inside the entity’s posting window. A date further back than the backdate window (180 days by default) returns 422 backdate_beyond_allowed_range, and a date further ahead of today (UTC) than the forward window (0 days by default) returns 422 future_beyond_allowed_range. To post outside the window on purpose, resend with backdate_reason or future_reason (4 to 500 characters); the override is granted only when the identity behind the call holds the accounting.close_period permission and an accounting period covers the date, and the reason is recorded on the entry’s audit row. General Ledger Fundamentals lists every refusal code.

Approval workflow

If your entity has approval thresholds configured, journal entries above the low threshold land in pending_approval status. GL does not post until the entry is approved. Check the status:

curl "https://api.arcuserp.com/v1/journal-entries/$JE_ID" \
  -H "Authorization: Bearer $ARCUS_API_KEY"
# Check: data.status

Approve (requires accounting:approve scope; approver must be a different user than the creator):

curl -s -X POST "https://api.arcuserp.com/v1/journal-entries/$JE_ID/approve" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

The status transitions to posted and the GL lines are active. The entry posts on its own entry_date, and the forward window is checked again at approval: an entry now dated further ahead of today than the window returns 422 future_beyond_allowed_range unless the approver sends future_reason, on the same terms as above.

Reversing a posted entry

GAAP requires an audit trail: you cannot modify or delete a posted journal entry. To undo one, create a reversing entry (scope accounting:write):

curl -s -X POST "https://api.arcuserp.com/v1/journal-entries/$JE_ID/reverse" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Incorrect account"
  }'

The body is optional and takes one field, reason. It becomes part of the reversing entry’s description (Reversal of JE-00128: Incorrect account); without it the description reads Reversal of JE-00128: Reversed via API. There is no date field: the reversing entry is dated the day of the call (UTC). The reversal is a new JE with all debits and credits swapped. The original entry is unchanged and both remain visible in the account ledger. The response is the new entry as it was posted: source_type is MANUAL_REVERSAL and source_id names the original. Arcus then links the two, storing is_reversing: true and reversal_of_id on the new entry and reversed_by_id on the original. Read those links back with GET /v1/journal-entries/{id} rather than from the reverse response.

Bank lines the reversal frees

If a bank statement line was matched to the original entry, the reversal returns that line to the review queue: the match is cleared, the line goes back to unreconciled, the entry’s leg on that bank account is no longer marked as cleared, and an activity record naming the reversal is written for each line. The response lists the freed lines in released_bank_transactions, an empty array when there were none (response abridged to the relevant fields):

{
  "source_type": "MANUAL_REVERSAL",
  "released_bank_transactions": [
    {
      "bank_transaction_id": "btx_uuid",
      "bank_account_id": "ba_uuid",
      "link_kind": "journal_entry",
      "transaction_date": "2026-05-31",
      "amount": 100.00,
      "unstamped": 1
    }
  ]
}

unstamped counts the entry’s lines on that bank account that are no longer marked as cleared (with a reason when none were). link_kind says which match was cleared: journal_entry when the line was matched to the reversed entry itself, marketplace_payout when it was matched to a payout that this entry posted. A marketplace_payout row whose match had posted a settlement correction also carries settlement_corrections_still_posted: that correction stays posted, and only the bank line’s own undo reverses it. A line that sits in a completed reconciliation (status reconciled) is not released; re-open or cancel that reconciliation first.

When a reversal is refused

Code	HTTP	Meaning
`je_not_posted`	409	Only a `posted` entry can be reversed; an entry in any other status has no GL effect to undo
`je_already_reversed`	409	The entry was already reversed
`je_target_is_reversing`	409	The entry is itself a reversal; its original is already reversed (reversing it returns `je_already_reversed`), so post a correcting entry
`not_found`	404	No journal entry with that id on your entity

Idempotency

Use a stable Idempotency-Key tied to your source record. For recurring entries, use a key that includes the period:

je-monthly-rent-2026-05
je-depreciation-equipment-2026-05
je-insurance-amort-2026-05

Replaying the same key within 24 hours returns the original response without creating a duplicate entry.

Closing an accounting period

When all entries for a period are in, close the period to prevent accidental future postings.

Step 1: Run the pre-close checklist

curl "https://api.arcuserp.com/v1/periods/$PERIOD_ID/close-checklist" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

The checklist reports blocking issues that should be resolved before close:

{
  "data": {
    "unposted_journal_entries": { "count": 0, "ids": [], "entry_numbers": [] },
    "pending_approval_entries": { "count": 0, "ids": [], "entry_numbers": [] },
    "unreconciled_bank_accounts": { "count": 1, "accounts": [] },
    "open_vendor_bills": { "count": 2, "total": 1840.5 },
    "outstanding_ar": { "count": 0, "total": 0 },
    "clearing_account_drains": [],
    "blocking_issues": [],
    "can_close": true
  }
}

can_close: true means blocking_issues is empty. open_vendor_bills and outstanding_ar are each an object with a count and a total, and the unreconciled bank accounts are a count for you to review. The checklist page shows open vendor bills and outstanding receivables as warnings, but the close calls treat them as blockers: POST /periods/{id}/close and approve-close also return 409 close_blocked_by_checklist while open vendor bills or outstanding AR invoices dated in the period remain, even when this checklist shows can_close: true. Each entry in blocking_issues is a sentence naming what to fix, and blocking_issue_details carries the same blockers as numbers. Common blocking issues:

Issue	What to do
Unposted journal entries in the period	Post or delete the draft entries
Pending-approval journal entries	Approve or reject them
Clearing account `blocking_issue`	Investigate unexplained drift in a marketplace clearing account

Step 2: Request close (two-person flow)

For separation of duties, use the two-step close:

# Step 2a: Request (any accounting:close_period user)
curl -s -X POST "https://api.arcuserp.com/v1/periods/$PERIOD_ID/request-close" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

# Step 2b: Approve (a different user with accounting:close_period + accounting:approve)
curl -s -X POST "https://api.arcuserp.com/v1/periods/$PERIOD_ID/approve-close" \
  -H "Authorization: Bearer $SECOND_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Reviewed May close" }'

The request moves the period from open to pending_approval. A period awaiting approval still accepts postings; it stops accepting them once it is closed. The approval moves it to closed, and before it does, it checks the request again:

Code	HTTP	Meaning
`sod_self_approval_forbidden`	403	The approver is the user who requested the close; a different user must approve
`period_not_in_pending_approval`	409	The period has no pending close request; the response carries `current_status`
`close_blocked_by_checklist`	409	The checklist reports blocking issues; the response lists them in `warnings`
`period_checksum_failed`	409	The period’s posted debits and credits do not balance; the response carries `delta`, `debits` and `credits`
`period_too_old_for_simple_close`	422	The period ended more than 180 days ago (see below)

To take back a request that has not been approved yet, POST /v1/periods/$PERIOD_ID/withdraw-close-request (optional body field reason) returns the period to open and clears the request. The person who made the request can withdraw it with accounting:close_period; withdrawing someone else’s request also needs accounting:approve.

Step 2 (alternative): Direct close

A key with accounting:close_period can close the period in one call, without a second approver:

curl -s -X POST "https://api.arcuserp.com/v1/periods/$PERIOD_ID/close" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "May close" }'

The checklist still applies, including open vendor bills and outstanding AR invoices dated in the period: while it reports blocking issues, the call returns 409 close_blocked_by_checklist with the blocking items in warnings. On success the response is the period with status closed.

Closing a period that ended more than 180 days ago

Both the approval and the direct close ask for an acknowledgement when the period ended more than 180 days ago. Closing an old period seals a range your books may already have been reported from, and reopening it later needs the same confirmation, so Arcus asks first. Without the flag, the call returns 422 (abridged):

{
  "error": "period_too_old_for_simple_close",
  "code": "period_too_old_for_simple_close",
  "type": "validation_error",
  "message": "This period ended 212 days ago, more than 180 days. Closing it seals a range the books may already have been reported from, and reopening it later will need the same confirmation, so it needs you to confirm that first.",
  "period_age_days": 212,
  "max_age_days_without_ack": 180,
  "hint_details": "Re-submit with body.acknowledge_old_period=true to confirm."
}

Re-send the same call with "acknowledge_old_period": true. This is a confirmation, not a permission: closing an old period is routine on books that are behind. On a period within 180 days, omit the flag and nothing changes.

After the close

Any attempt to create a journal entry with an entry_date inside a closed period returns 422 (abridged):

{
  "error": "period_closed",
  "message": "Cannot post to closed accounting period \"May 2026\".",
  "period_name": "May 2026",
  "requested_date": "2026-05-15",
  "next_open_period_start": "2026-06-01"
}

next_open_period_start is the first day you can post to instead (null when no later period is open).

Reopening a period

If you need to post a correcting entry after close (scope accounting:close_period):

curl -s -X POST "https://api.arcuserp.com/v1/periods/$PERIOD_ID/reopen" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Reposting the May COGS reclass after the inventory count"
  }'

The body fields:

Field	Required	What it does
`reason`	Yes	Why the period is reopened, 10 to 500 characters. Stored on the period as `reopen_reason` and written to the audit trail
`acknowledge_old_period`	When the period ended more than 180 days ago	Confirms you mean to reopen an old period
`sod_override_authorized_by`	Only for a self-reopen	The user id of the person who authorizes you to reopen a period whose close you requested or approved (see below)

The period returns to open. The close tracking fields are cleared, reopened_by and reopened_at are set, and an activity record with the reason and the period’s prior state is written. Reopen + correcting entry + re-close is the standard GAAP path for post-close adjustments. Separation of duties. The user who requested or approved the period’s close cannot reopen it alone; the call returns 403 sod_self_reopen_forbidden. When there is no second person to do it (a single-owner company, for example), send sod_override_authorized_by with the user id of whoever authorizes the reopen. That user must hold an active membership on your entity with the close-period permission, and may be you. The call still records you as the person who reopened the period, and it writes a separate activity record naming the override and who authorized it. When a reopen is refused:

Code	HTTP	Meaning
`reason_required`	400	No `reason` was sent
`reason_length_invalid`	422	`reason` is shorter than 10 or longer than 500 characters
`period_not_closed`	409	Only a `closed` period can be reopened; the response carries `current_status`
`sod_self_reopen_forbidden`	403	You requested or approved this period’s close; send `sod_override_authorized_by`
`sod_override_authorizer_invalid`	422	`sod_override_authorized_by` is not a user id
`sod_override_authorizer_not_member`	403	The authorizer has no active membership on this entity
`sod_override_authorizer_lacks_permission`	403	The authorizer does not hold the close-period permission on this entity
`period_too_old_for_simple_reopen`	422	The period ended more than 180 days ago; resend with `acknowledge_old_period: true`
`period_state_changed`	409	Another close or reopen changed the period at the same moment; retry

A period closed by the fiscal year-end close has status year_end_closed and is not reopened here: use POST /v1/fiscal-periods/{id}/reopen-fiscal-year, which also reverses the closing entry.

Year-end closing entries

At fiscal year-end, revenue and expense account balances are swept into Retained Earnings (account 3000). As of 2026-05-13, Arcus exposes POST /v1/accounting_periods/{id}/close-fiscal-year for automated closing-entry generation per GAAP:

# Automated year-end close (recommended): posts the canonical closing JE
# sweeping revenue/expense -> Retained Earnings in one idempotent call.
curl -s -X POST "https://api.arcuserp.com/v1/fiscal-periods/$PERIOD_ID/close-fiscal-year" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fiscal_year": 2026,
    "fy_start_date": "2026-01-01",
    "fy_end_date": "2026-12-31"
  }'
# Returns: { data: { je_id, fiscal_year, net_income_loss, balanced: true, idempotent } }
# Re-running returns the existing JE without double-posting (idempotent).

The body takes fiscal_year, fy_start_date and fy_end_date, all three required, and the call needs accounting:close_period. POST /v1/accounting_periods/{id}/close-fiscal-year is an alias that accepts the same body. Precondition: all monthly periods in the fiscal year must be in closed or pending_approval status before calling this endpoint.

Reopening a fiscal year

POST /v1/fiscal-periods/{id}/reopen-fiscal-year (scope accounting:close_period) reverses a year-end close. Send fiscal_year and a reason of up to 500 characters. Arcus posts the sign-flipped inverse of the original closing entry, leaves the original entry unchanged, and returns the fiscal year’s last period to closed. Re-running it for a year already reopened returns the existing reversal entry (idempotent: true) instead of posting a second one. Balance sheet after close: GET /v1/reports/balance-sheet returns retained_earnings from the booked account 3000 balance plus current_year_earnings showing any un-closed post-close activity separately. Manual closing entries (power-user alternative): if you need per-account line control, you can still post manual JEs through POST /v1/journal-entries:

# Manual close -- revenue into retained earnings (power user)
curl -s -X POST "https://api.arcuserp.com/v1/journal-entries" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: year-end-close-revenue-FY2026" \
  -d '{
    "entry_date": "2026-12-31",
    "description": "FY2026 year-end close - revenue to retained earnings",
    "source_type": "FISCAL_YEAR_CLOSE",
    "lines": [
      { "account_id": "gl_sales_revenue_uuid",   "debit": 485000.00 },
      { "account_id": "gl_retained_earnings_uuid", "credit": 485000.00 }
    ]
  }'

Repeat for COGS and expense accounts (the net becomes your net income for the year). After posting all closing entries, the income statement accounts should show zero balances and only balance sheet accounts should have non-zero balances.

Running reports to verify

Before closing, confirm the trial balance is in balance:

curl "https://api.arcuserp.com/v1/reports/trial-balance?period_id=$PERIOD_ID" \
  -H "Authorization: Bearer $ARCUS_API_KEY"
# Check: is_balanced == true, total_debits == total_credits

Check AR, AP and inventory subledger reconciliation:

curl "https://api.arcuserp.com/v1/reports/subledger-reconciliation" \
  -H "Authorization: Bearer $ARCUS_API_KEY"
# Check: each of ar, ap and inventory shows gl_balance and subledger_balance
#        side by side with variance == 0 (status "balanced")

The reconciliation compares balances as of the entity’s current business day. It rejects the deprecated as_of_date parameter with 400 unsupported_param, and subledger_type narrows it to one subledger.

Common errors

Code	HTTP	Meaning
`gl_imbalance`	422	Debit sum does not equal credit sum
`account_is_header`	422	Line targets a rollup account; use a leaf account
`account_inactive`	422	Account is deactivated; reactivate or use a different account
`account_not_found`	422	account_id does not exist for this entity
`period_closed`	422	entry_date falls in a closed period
`backdate_beyond_allowed_range`	422	entry_date is further back than the entity’s backdate window; resend with `backdate_reason` if you may override
`future_beyond_allowed_range`	422	entry_date is further ahead of today than the entity’s forward window; resend with `future_reason` if you may override
`sod_self_approval_forbidden`	403	The approver created the journal entry, or requested the period close (SoD violation)
`close_blocked_by_checklist`	409	Checklist has blocking issues; resolve them first
`period_too_old_for_simple_close`	422	The period ended more than 180 days ago; resend the close or approval with `acknowledge_old_period: true`
`je_already_reversed`	409	The journal entry was already reversed
`sod_self_reopen_forbidden`	403	You requested or approved the close you are trying to reopen
`permission_denied`	403	The user who created the API key lacks the permission this action needs
`insufficient_scope`	403	Missing accounting:write, accounting:approve, or accounting:close_period

Next steps

GL Fundamentals — chart of accounts structure, system account keys, and financial reports
Purchase-to-Pay Flow — how PO receipts and vendor bills post GL entries automatically
API Reference: Journal Entries
API Reference: Accounting Periods
API Reference: Financial Reports

Get Started

Concepts

Guides

SDKs

Collections

Journal Entries and Period Close

What this guide covers

Prerequisites

The two non-negotiable rules

1. Debits must equal credits

2. Post to leaf accounts only

Posting a manual journal entry

Example: prepaid insurance amortization

Response shape

The posting window

Approval workflow

Reversing a posted entry

Bank lines the reversal frees

When a reversal is refused

Idempotency

Closing an accounting period

Step 1: Run the pre-close checklist

Step 2: Request close (two-person flow)

Step 2 (alternative): Direct close

Closing a period that ended more than 180 days ago

After the close

Reopening a period

Year-end closing entries

Reopening a fiscal year

Running reports to verify

Common errors

Next steps

​What this guide covers

​Prerequisites

​The two non-negotiable rules

​1. Debits must equal credits

​2. Post to leaf accounts only

​Posting a manual journal entry

​Example: prepaid insurance amortization

​Response shape

​The posting window

​Approval workflow

​Reversing a posted entry

​Bank lines the reversal frees

​When a reversal is refused

​Idempotency

​Closing an accounting period

​Step 1: Run the pre-close checklist

​Step 2: Request close (two-person flow)

​Step 2 (alternative): Direct close

​Closing a period that ended more than 180 days ago

​After the close

​Reopening a period

​Year-end closing entries

​Reopening a fiscal year

​Running reports to verify

​Common errors

​Next steps

What this guide covers

Prerequisites

The two non-negotiable rules

1. Debits must equal credits

2. Post to leaf accounts only

Posting a manual journal entry

Example: prepaid insurance amortization

Response shape

The posting window

Approval workflow

Reversing a posted entry

Bank lines the reversal frees

When a reversal is refused

Idempotency

Closing an accounting period

Step 1: Run the pre-close checklist

Step 2: Request close (two-person flow)

Step 2 (alternative): Direct close

Closing a period that ended more than 180 days ago

After the close

Reopening a period

Year-end closing entries

Reopening a fiscal year

Running reports to verify

Common errors

Next steps