> For the complete documentation index, see [llms.txt](https://docs.kick.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kick.co/api/api-reference/locks.md).

# Locks

Read and set the lock dates that close the books of the entities in your client workspaces.

A lock date closes an entity's books through that calendar day, inclusive. Kick then blocks changes to transactions and journal entries dated on or before it, from the Kick app and from this API alike: a blocked write answers `409`, as described on [Transactions](https://docs.kick.co/api/api-reference/transactions.md) and [Journal Entries](https://docs.kick.co/api/api-reference/journal-entries.md).

An entity has at most one lock, so a lock is addressed by its entity's uuid rather than an id of its own. Each lock carries `entityId`, `workspaceId`, and `date` as `YYYY-MM-DD`.

### List locks

The list covers one workspace at a time, named by the required `workspaceId` query param. Only entities that have a lock date are returned; an entity that was never locked, or was unlocked, is left out.

* `workspaceId` takes exactly one uuid.
* `entityIds` narrows the list further. It takes a single uuid or a repeated query param. An entity of your organization that sits in another workspace returns no lock.
* Results are ordered by when the entity was created and paged with `limit` and `offset`. See [Paging](https://docs.kick.co/api/readme.md#paging).

```bash
curl "https://use.kick.co/api/platform/v1/locks?workspaceId=8d3a1b52-9f1d-4a7e-b0a1-2c5d6e7f8a90" \
  -H "Authorization: Bearer kick_org_..."
```

## List locks

> Returns the lock of every entity in the workspace that has a lock date. Entities that are unlocked are left out. \`entityIds\` narrows the list further. A workspace outside the organization returns 404; an entity outside it is rejected with 400. Results are ordered by entity creation and paged with \`limit\`/\`offset\`.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/locks":{"get":{"description":"Returns the lock of every entity in the workspace that has a lock date. Entities that are unlocked are left out. `entityIds` narrows the list further. A workspace outside the organization returns 404; an entity outside it is rejected with 400. Results are ordered by entity creation and paged with `limit`/`offset`.","operationId":"locks.list","parameters":[{"in":"query","name":"limit","schema":{"default":100,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"nullable":true,"type":"integer"}},{"in":"query","name":"workspaceId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Only locks of these entities. A single value or a repeated `entityIds` query param both work. An entity outside the organization is rejected.","in":"query","name":"entityIds","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"date":{"description":"Last locked calendar day, as YYYY-MM-DD. Null when the entity is unlocked.","format":"date","nullable":true,"type":"string"},"entityId":{"format":"uuid","type":"string"},"workspaceId":{"format":"uuid","type":"string"}},"required":["entityId","workspaceId","date"],"type":"object"},"type":"array"},"pagination":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"],"type":"object"}},"required":["data","pagination"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"List locks","tags":["locks"]}}}}
```

### Update an entity's lock date

The body names the entity and the new `date`. The date replaces whatever lock date the entity had, so it can move the lock forward or back. A `null` date unlocks the entity. The response carries the lock as stored, and an unlocked entity comes back with `date: null`.

* When the date actually changes, Kick sends the [`entity.lock_date.changed`](https://docs.kick.co/api/webhooks/entity-lock-date-changed.md) webhook. Sending the date the entity already has changes nothing and sends no event.

```bash
curl -X PUT "https://use.kick.co/api/platform/v1/locks" \
  -H "Authorization: Bearer kick_org_..." \
  -H "Content-Type: application/json" \
  -d '{"entityId": "b6c4d2e1-7a3f-4c8b-9e0d-1f2a3b4c5d6e", "date": "2026-09-30"}'
```

## Update an entity's lock date

> Locks the books of an entity through \`date\`, inclusive: Kick blocks changes to transactions and journal entries dated on or before it. A null \`date\` unlocks the entity. When the date changes, Kick sends the \`entity.lock\_date.changed\` webhook.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/locks":{"put":{"description":"Locks the books of an entity through `date`, inclusive: Kick blocks changes to transactions and journal entries dated on or before it. A null `date` unlocks the entity. When the date changes, Kick sends the `entity.lock_date.changed` webhook.","operationId":"locks.set","parameters":[{"description":"A unique key that makes the request idempotent. Retrying with the same key within 24 hours replays the original response (marked with `Idempotent-Replayed: true`) instead of executing again.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":255,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"date":{"description":"Last calendar day to lock, as YYYY-MM-DD. Null unlocks the entity.","format":"date","nullable":true,"type":"string"},"entityId":{"format":"uuid","type":"string"}},"required":["entityId","date"],"type":"object"}}},"description":"Body"},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"lock":{"properties":{"date":{"description":"Last locked calendar day, as YYYY-MM-DD. Null when the entity is unlocked.","format":"date","nullable":true,"type":"string"},"entityId":{"format":"uuid","type":"string"},"workspaceId":{"format":"uuid","type":"string"}},"required":["entityId","workspaceId","date"],"type":"object"}},"required":["lock"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"Update an entity's lock date","tags":["locks"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kick.co/api/api-reference/locks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
