Close Period
POST/api/ledger/close/periods/:period/close
Close and lock the period. Only the earliest non-closed month can close (periods close strictly in order). Every failing blocking check refuses the close; every warning-level failure and incomplete manual item must be listed in acknowledged_keys. The close runs as a background job that re-validates all gates, snapshots the report pack, inserts the period lock (new entries dated on or before the period end are refused; corrections are redated to the first open day), and records the sign-off. Returns the background job id.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Authentication: Bearer token. Requires the accounting settings management permission.
Errors: 422 when a blocking check fails, an acknowledgement is missing, the month is out of order, or another close is already running.
overrides: an optional object of {check key: reason} for blocking checks that permit being closed over. Only checks flagged can_be_overridden in the checklist accept one, the reason is required and is stored with the close, and the caller must hold the matching permission - otherwise the request is refused with 403. Today the only such check is inventory_debt_outstanding, which blocks while units that shipped without stock are still owed; closing over it records the reason together with the number of outstanding claims and the unrelieved clearing balance at that moment. Checks that are not overridable, such as unbalanced entries, still refuse the close at any permission level.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.