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

  1. Period locks can only be created, not updated or deleted
  2. 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_date reopens the days between the two dates; the older locks stay in the list as history
  3. 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 with 409 accounting.period_locked. Drafts are not checked
  4. Users must have access to the client account to create or view period locks
  5. A locking comment must be provided to document the reason for the lock

Common Use Cases

  1. Locking completed accounting periods after month-end closing
  2. Preventing modifications to historical data after tax reporting
  3. Maintaining data integrity during audits
  4. Ensuring compliance with accounting regulations

Best Practices

  1. Always provide clear and descriptive locking comments
  2. Set period locks immediately after completing period-end procedures
  3. Consider regulatory requirements when determining lock periods
  4. Review existing period locks before creating new ones