> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# update_statements_status

> Lock, unlock, pay or unpay up to 50 statements, and request their validation when locking. One row per statement says what happened to it.

Lock, unlock, pay or unpay statements, and request their validation when
locking.

Locking freezes a statement's amounts, the step before it can be approved and
paid. Paying marks a locked statement as sent to payroll, and unpaying cancels
that payment. Pass the statement ids
[`list_statements`](https://docs.qobra.co/mcp_documentation/tools/list_statements) returns, at most
50 per call. Only statements you can see can be changed.

Each statement sent gets one row saying what happened to it:

* Changed: `locked`, `locked_and_validation_requested`, `validation_requested`,
  `unlocked`, `paid` or `unpaid`.
* Skipped, with the reason in `reason`: already locked, paid, in error, still
  being calculated, or a validation already requested.
* Failed on Qobra's side, in which case it may be changed in part. `reason`
  says what to do.

A row may carry a `warning`, such as the previous period of that user left
unlocked. Sending a state already there skips the statement, so you can send
the same call again.

Unlocking is destructive. Qobra recalculates the statement's amounts. For a
company that has validation workflows, Qobra also clears the statement's
validation workflow with every approval already given, even while the module is
switched off in the settings. A paid statement cannot be unlocked: unpay it
first.

Paying needs a locked statement with no calculation error, and none of its
validation workflow's mandatory stages still awaiting approval. Paying is an
outbound action. Qobra notifies the owner of each statement paid and, where the
company has a live payroll webhook, sends the statement to it, as from the web
app. No payment date is recorded. To approve the stages a payment waits on, use
[`approve_statements`](https://docs.qobra.co/mcp_documentation/tools/approve_statements).

Unpaying cancels the payment in Qobra only: it recalls nothing already sent to
payroll, and leaves the statement locked. It refuses a statement whose last
validation is not its payment.

To request a validation, pass `validation_workflow_template_id` with `lock`.
Read the template ids with
[`list_validation_workflow_templates`](https://docs.qobra.co/mcp_documentation/tools/list_validation_workflow_templates).
A statement still open is locked first when your role may lock; one already
locked gets the workflow only. Qobra assigns the template's workflow and
notifies its approvers, as the web app does.

The whole call is refused before anything changes when one id names no
statement you can see, or when the validation workflow is switched off and a
template is passed. Each statement changes in the environment it lives in.

Locking and unlocking require the lock permission on statements. Paying and
unpaying require the payment permission. Requesting a
validation on a statement already locked requires only the permission to
request one. Available only where the Qobra write tools beta is enabled.
Every write to the live environment is recorded in the audit trail as the
`Qobra MCP` agent; writes to a sandbox are not audited.

## Parameters

> [accordion] Body
>
> **statement\_ids** `string[]` *required*
>
> Ids of the statements to change — the ids list\_statements returns. At most
> 50 per call.
>
> **action** `string` *required*
>
> lock freezes the statements' amounts, the step before they can be approved
> and paid. unlock reopens locked statements. pay marks locked statements as
> sent to payroll. unpay cancels that payment, leaving them locked. One of:
> `lock`, `unlock`, `pay`, `unpay`.
>
> **validation\_workflow\_template\_id** `string`
>
> With lock only: the id of the validation workflow to request on each
> statement, one of list\_validation\_workflow\_templates' ids. A statement still
> open is locked first when your role may lock; one already locked gets the
> workflow only. Omit it to lock without requesting a validation.

## Example

Lock two statements and request their validation:

```json theme={null}
{
  "statement_ids": ["66a0b1c2d3e4f50012345678", "66a0b1c2d3e4f50012345679"],
  "action": "lock",
  "validation_workflow_template_id": "66a0b1c2d3e4f50012349999"
}
```

Mark locked statements as paid:

```json theme={null}
{
  "statement_ids": ["66a0b1c2d3e4f50012345678"],
  "action": "pay"
}
```

## Response

> [accordion] Body
>
> **statements** `object[]`
>
> One row per statement, in the order first sent: an id sent twice is changed
> and reported once.
>
> **object properties**
>
> **id** `string`
>
> **resource\_url** `string`
>
> Deep link to open this statement in the Qobra web app.
>
> **user** `object`
>
> **object properties**
>
> **id** `string`
>
> **email** `string`
>
> **name** `string`
>
> **period** `string`
>
> **outcome** `string`
>
> What the call did to this statement:
>
> * locked: locked, its amounts frozen.
> * locked\_and\_validation\_requested: locked, then the validation workflow
>   of the template was assigned.
> * validation\_requested: already locked, the workflow was assigned.
> * unlocked: unlocked, and its calculation relaunched.
> * paid: marked as sent to payroll.
> * unpaid: its payment cancelled, still locked.
> * skipped: left as it was, `reason` says why.
> * failed: an error on our side interrupted it, so it may be changed in
>   part; `reason` says what to do. One of: `locked`,
>   `locked_and_validation_requested`, `validation_requested`, `unlocked`,
>   `paid`, `unpaid`, `skipped`, `failed`.
>
> **reason** `string`
>
> Why the statement was skipped or failed; null otherwise.
>
> **warning** `string`
>
> Something to tell the user about a statement that did change, such as an
> earlier period of theirs left unlocked; null when there is nothing to
> flag.
>
> **payment\_status** `string`
>
> After the call. What the statement's payment is waiting on:
>
> * blocked\_by\_error: a calculation error blocks locking and payment until
>   it is fixed.
> * awaiting\_lock: still open, its amounts can change; a statement is
>   locked before it can be paid.
> * awaiting\_approval: locked, but a mandatory stage of its validation
>   workflow is still waiting on an approver (see
>   `validation_workflow.blocking_stage`).
> * awaiting\_payroll: locked and nothing blocks it, not yet sent to
>   payroll.
> * paid: sent to payroll. One of: `blocked_by_error`, `awaiting_lock`,
>   `awaiting_approval`, `awaiting_payroll`, `paid`.
>
> **awaited\_approvers** `object[]`
>
> After the call, the approvers whose turn it is. Empty when nothing
> awaits an approval.
>
> **object properties**
>
> **user** `object`
>
> **object properties**
>
> **id** `string`
>
> **email** `string`
>
> **name** `string`
>
> **last\_reminded\_at** `string`
>
> When they were last reminded to approve; null if never.