MagicDoorAPI
SupportOpen MagicDoor
Reconciliation periods

Lock a reconciliation period

Closes a period: freezes its items into a snapshot and stops them being resolved or rematched. Requires the reconciliations:write permission.

POST
https://services.magicdoor.com/accounting/company-portal/reconciliations/periods/{reconciliationPeriodId}/lock

Authorization

Authorizationstringrequired
Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Path parameters

reconciliationPeriodIdstringrequired

Snowflake id of the reconciliation period.

example: 1830472847398411100

Response

200 · The period, now `locked`, with `locked` set.

idstring

Snowflake id of the period.

bankAccountIdstring

The bank account this period covers.

periodStartstring · date

First day of the period, in the company's timezone.

periodEndstring · date

Last day of the period, in the company's timezone.

openingBalancenumber

The bank's balance at the start of the period, as a decimal.

closingBalancenumber

The bank's balance at the end of the period, as a decimal, taken from the statement.

statusenum<string>

draft while being prepared, locked once closed, reopened after a locked period has been opened up again. Both draft and reopened are editable.

draftreopenedlocked
validityStatusenum<string>

Only meaningful once locked. valid when nothing outstanding affects it; invalidated when it has an unacknowledged disposition of its own; impacted when an earlier period is invalidated, so this one's numbers are indirectly in doubt. A draft or reopened period is always valid.

validinvalidatedimpacted
dispositionsDisposition[]

Things that changed after this period was locked and are waiting to be acknowledged.

lockedstring · date-time

When the period was locked, in the company's timezone. Absent while it is draft or reopened.

createdstring · date-time

When the period was created, in the company's timezone.

updatedstring · date-time

When it last changed, in the company's timezone.

401 · The access token is missing, expired, or not for this company.

403 · The caller does not hold the `reconciliations:write` permission.

404 · No reconciliation period with this id belongs to the caller's company.

422 · One or more lock conditions are unmet. The `detail` describes the blocking condition; read `blockers` on the period for the full list.

What has to be true before it locks

Locking is refused unless every one of these holds. Read the period first — capabilities.canLock gives the answer and blockers with action: "lock" names what is missing.

  • financialSummary.difference is exactly zero
  • every bank feed entry in the period has a reconciliation item
  • every one of those items is resolved, with no unacknowledged review
  • no item is already locked into another period
  • every resolved item has exactly the transaction links it should
  • the period has no unacknowledged dispositions
  • no earlier period on the account is still draft or reopened
Locking freezes the items

Once locked, the items inside carry lockedPeriodId and refuse resolve, rematch and candidate generation. To touch them again the period has to be reopened.