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 and Journal Entries.
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.
workspaceIdtakes exactly one uuid.entityIdsnarrows 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
limitandoffset. See Paging.
curl "https://use.kick.co/api/platform/v1/locks?workspaceId=8d3a1b52-9f1d-4a7e-b0a1-2c5d6e7f8a90" \
-H "Authorization: Bearer kick_org_..."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.
Organization access token issued by Kick, sent as Authorization: Bearer kick_org_....
1000Only locks of these entities. A single value or a repeated entityIds query param both work. An entity outside the organization is rejected.
200
400
401
404
429
GET /api/platform/v1/locks?workspaceId=123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: use.kick.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"date": "YYYY-MM-DD",
"entityId": "123e4567-e89b-12d3-a456-426614174000",
"workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}
],
"pagination": {
"limit": 1,
"offset": 1,
"total": 1
}
}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.changedwebhook. Sending the date the entity already has changes nothing and sends no event.
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.
Organization access token issued by Kick, sent as Authorization: Bearer kick_org_....
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.
Last calendar day to lock, as YYYY-MM-DD. Null unlocks the entity.
YYYY-MM-DD200
400
401
404
429
PUT /api/platform/v1/locks HTTP/1.1
Host: use.kick.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71
{
"date": "YYYY-MM-DD",
"entityId": "123e4567-e89b-12d3-a456-426614174000"
}{
"lock": {
"date": "YYYY-MM-DD",
"entityId": "123e4567-e89b-12d3-a456-426614174000",
"workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}
}Last updated
Was this helpful?
