API / Concepts
Periods and locks
Why a posting is rejected with ACCOUNTING_PERIOD_CLOSED or ACCOUNTING_PERIOD_LOCKED, and what to do about it.
Once a month has been reported, its numbers must stop moving. Accounting periods are how Light guarantees that, and they are the reason a request that worked yesterday can fail today with ACCOUNTING_PERIOD_CLOSED.
Periods
An accounting period is a company-wide slice of time, usually a month, with two statuses: OPEN and CLOSED. Every operation that changes the ledger (post, reverse, clear, unclear) is checked against the period that contains its posting date. Not the document date, and not today: the postingDate on the document (a journal entry's defaults to today).
Periods are generated on demand by the company, not automatically. A date that no generated period covers is unprotected: postings into it are allowed. Companies normally generate periods ahead, so treat an unexpected success on a far-future or far-past date as something to raise, not something to rely on.
Locks
Closing is the final step. Before it, each period carries four close tasks, and three of them are soft locks that a controller can complete per entity while the month is still being finished:
| Task | Blocks |
|---|---|
| Lock AP | Posting, reversing and clearing bills (AP) for the entities marked complete |
| Lock AR | The same for sales invoices (AR) |
| Lock JE | The same for journal entries (JE) |
| FX revaluation | Runs the period's revaluation; it does not block postings |
Only bills, sales invoices and journal entries can be soft-locked. Bank payments, card transactions, credits and system entries are stopped only by a fully closed period.
What the errors mean
| Error type | Meaning | What to do |
|---|---|---|
ACCOUNTING_PERIOD_CLOSED |
The period covering the posting date is closed for everything. | Post into an open period, or ask the company's controller to reopen. Reopening a period reopens every later period as well, so it is not a small ask. |
ACCOUNTING_PERIOD_LOCKED |
The period is open, but the lock task for this document type (and, if the message names one, this entity) is complete. | Post into a later period, or ask for the lock to be lifted for that entity. |
Both checks run before anything else in the posting pipeline, so a rejected posting consumes no document number and writes nothing.
Reversals are postings too
Reversing a posted document writes new ledger lines dated with the original posting date, not today's. So archiving a journal entry that was posted in March fails in June if March is closed, and unclearing a March payment does the same. If the period cannot be reopened, the correction is a new, opposite journal entry in the current period.
Year end
Closing an accounting year posts a year-closing entry (YC) that moves the year's profit or loss into retained earnings. Its lines appear on List ledger transaction lines like any other, with documentType: "YC". If you compute a balance sheet from ledger lines across a year end, include them. If you compute a profit and loss statement, exclude them, or the year sums to zero.
Next: Choosing an endpoint.