Period Locks
Period locks are used to prevent modifications to accounting data in closed periods. This helps maintain data integrity and ensures compliance with accounting regulations by preventing unauthorized changes to historical records.
Endpoints
List Period Locks
GET /api/v2/period-locks
Retrieves a paginated list of period locks for a specific client account, newest first. The first lock in the list is the one in force.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | The ID of the client account |
| page | integer | No | Page number (default: 1) |
| per_page | integer | No | Items per page (default: 100) |
| with | string | No | Include related resources (supported: created_by) |
Response
{
"data": [
{
"id": 123,
"client_account_id": 456,
"locked_until_date": "2024-03-31",
"locking_comment": "Q1 2024 closed",
"created_at": "2024-04-01T10:00:00.123456+00:00",
"created_by_id": 789,
"created_by": { // Only included when with=created_by
"id": 789,
"first_name": "John",
"last_name": "Doe",
"created_at": "2023-01-01T00:00:00+00:00",
"profile_image_url": null,
"last_login": "2024-03-15T14:30:00+00:00"
}
}
],
"meta": {
"page": 1,
"pages": 1,
"per_page": 100,
"records": 1
}
}
Create Period Lock
POST /api/v2/period-locks
Creates a new period lock for a client account. The new lock replaces the one in force, whether its date is later or earlier: see Business Rules.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | The ID of the client account |
| locked_until_date | string | Yes | The last locked day, inclusive (YYYY-MM-DD) |
| locking_comment | string | Yes | Comment explaining the reason for the lock, at most 255 characters. An empty string is refused |
Example Request
{
"client_account_id": 456,
"locked_until_date": "2024-03-31",
"locking_comment": "Q1 2024 closed"
}
Response
Returns the created lock with status 201 Created.
{
"id": 123,
"client_account_id": 456,
"locked_until_date": "2024-03-31",
"locking_comment": "Q1 2024 closed",
"created_at": "2024-04-01T10:00:00.123456+00:00",
"created_by_id": 789
}
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | common.validation_error |
A missing client_account_id on GET; a missing request body, client_account_id, locked_until_date or locking_comment on POST |
| 400 | common.serialization_error |
POST with a locked_until_date that isn’t a YYYY-MM-DD date, or a client_account_id that isn’t a number |
| 403 | accounting.client_account_access_denied |
No access to the supplied client_account_id |
Business Rules
- Period locks can only be created, not updated or deleted
- The lock in force is the most recently created one, not the one with the latest date. Creating a lock with an earlier
locked_until_datereopens the days between the two dates; the older locks stay in the list as history - While a lock is in force, nothing can be posted or reversed on or before its
locked_until_date: journal entries with such a posting date are refused with409accounting.period_locked. Drafts are not checked - Users must have access to the client account to create or view period locks
- A locking comment must be provided to document the reason for the lock
Common Use Cases
- Locking completed accounting periods after month-end closing
- Preventing modifications to historical data after tax reporting
- Maintaining data integrity during audits
- Ensuring compliance with accounting regulations
Best Practices
- Always provide clear and descriptive locking comments
- Set period locks immediately after completing period-end procedures
- Consider regulatory requirements when determining lock periods
- Review existing period locks before creating new ones