> ## 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_statement_payments

> Add, change or remove the manual payment lines of one statement, and set or reset its draw and carried balance. All or nothing.

Add, change or remove the manual payment lines of one statement, and set or
reset its draw and its carried balance.

Only what is sent is written. A manual payment line left out stays, and an
argument left out leaves that part of the statement as it is:

* Add a line without a `payment_id`.
* Change a line with the `payment_id`
  [`get_statement`](https://docs.qobra.co/mcp_documentation/tools/get_statement) lists on it.
* Remove a line with `value: null`.

Amounts are in the statement's calculation currency.

The draw and the carried balance need draws to be on for the company, as
[`get_company_settings`](https://docs.qobra.co/mcp_documentation/tools/get_company_settings) reports.
Setting a draw by hand also rewrites the balance carried by the empty statements
that follow, locked and paid ones included, as in the Qobra web app.

The call is all or nothing. An unknown `payment_id`, a new line without a label
or a value, or a missing reason refuses the whole call before anything is
written. A locked statement is refused. When the company requires a reason for
statement adjustments, each change cites one of the `adjustment_reasons`
get\_statement lists. When the company requires none (`adjustment_reasons` is
null), a `reason` is refused: put a free-text note in `comment` instead. Qobra
notifies the user of each change, as from the web app.

The statement's total and balance are up to date when the call returns; no
recalculation is needed. To override a computed value instead, use
[`update_statement_adjustments`](https://docs.qobra.co/mcp_documentation/tools/update_statement_adjustments).

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\_id** `string` *required*
>
> Id of the statement to adjust — the id list\_statements returns.
>
> **manual\_payments** `object[]`
>
> Manual payment lines to add, change or remove. At most 50 per call. Omit it
> to leave the lines as they are.
>
> **object properties**
>
> **payment\_id** `string`
>
> Id of the manual payment line to change or remove, a `payment_id`
> get\_statement lists. Omit it to add a new line.
>
> **label** `string`
>
> The line's label, as the statement shows it. Required for a new line;
> omit it to keep the label of an existing one.
>
> **value** `number | null` *required*
>
> The amount, in the statement's calculation currency; negative to
> deduct. null removes the line.
>
> **reason** `string`
>
> Why the line is written, one of the `adjustment_reasons` get\_statement
> lists. Required when that list is not null, refused when it is `null`: a
> free-text note goes in `comment`.
>
> **comment** `string`
>
> A comment kept with the change in the statement's activity.
>
> **draw** `object`
>
> The draw (recoverable advance) to set by hand on this statement, or null as
> its value to go back to the automatic draw. Omit it to leave the draw as it
> is.
>
> **object properties**
>
> **value** `number | null` *required*
>
> The amount, in the statement's calculation currency. null removes the
> manual value and brings the automatic one back.
>
> **reason** `string`
>
> Why the value is set, one of the `adjustment_reasons` get\_statement
> lists. Required when that list is not null, refused when it is `null`: a
> free-text note goes in `comment`.
>
> **comment** `string`
>
> A comment kept with the change in the statement's activity.
>
> **carried\_balance** `object`
>
> The opening balance to set by hand instead of the one carried from the
> previous statement, or null as its value to carry it again. Omit it to leave
> it as it is.
>
> **object properties**
>
> **value** `number | null` *required*
>
> The amount, in the statement's calculation currency. null removes the
> manual value and brings the automatic one back.
>
> **reason** `string`
>
> Why the value is set, one of the `adjustment_reasons` get\_statement
> lists. Required when that list is not null, refused when it is `null`: a
> free-text note goes in `comment`.
>
> **comment** `string`
>
> A comment kept with the change in the statement's activity.

## Example

Add a manual payment line, remove another one and set the draw by hand:

```json theme={null}
{
  "statement_id": "66a0b1c2d3e4f50012345678",
  "manual_payments": [
    { "label": "Q3 spiff", "value": 500, "reason": "Sales contest" },
    { "payment_id": "66a0b1c2d3e4f50012345555", "value": null }
  ],
  "draw": { "value": 1000, "comment": "Ramp-up advance" }
}
```

## Response

> [accordion] Body
>
> **statement\_id** `string`
>
> **resource\_url** `string`
>
> Deep link to the statement in the Qobra web app.
>
> **manual\_payments** `object[]`
>
> One row per manual payment sent, in the order sent.
>
> **object properties**
>
> **payment\_id** `string`
>
> **label** `string`
>
> **value** `number`
>
> The amount sent; null when the line was removed.
>
> **action** `string`
>
> What the call did: created (a new manual value), updated (another value
> on an existing one), removed (the manual value is gone, the automatic
> one is back), unchanged (nothing to write: the value is already the one
> sent, or there was nothing to remove). One of: `created`, `updated`,
> `removed`, `unchanged`.
>
> **draw** `object`
>
> What became of the draw; null when it was not sent.
>
> **object properties**
>
> **value** `number`
>
> The amount sent; null when it asked for the automatic value back.
>
> **action** `string`
>
> What the call did: created (a new manual value), updated (another value
> on an existing one), removed (the manual value is gone, the automatic
> one is back), unchanged (nothing to write: the value is already the one
> sent, or there was nothing to remove). One of: `created`, `updated`,
> `removed`, `unchanged`.
>
> **carried\_balance** `object`
>
> What became of the carried balance; null when it was not sent.
>
> **object properties**
>
> **value** `number`
>
> The amount sent; null when it asked for the automatic value back.
>
> **action** `string`
>
> What the call did: created (a new manual value), updated (another value
> on an existing one), removed (the manual value is gone, the automatic
> one is back), unchanged (nothing to write: the value is already the one
> sent, or there was nothing to remove). One of: `created`, `updated`,
> `removed`, `unchanged`.
>
> **total\_amount** `number`
>
> Net amount to be paid out on the statement after the call, in `currency`:
> its lines, manual payments and draw together.
>
> **currency** `string`
>
> The statement's calculation currency, which every amount here and in the
> call is in. One of: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`,
> `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`,
> `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYR`, `BZD`, `CAD`, `CDF`, `CHF`, `CLF`,
> `CLP`, `CNY`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`,
> `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`,
> `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`,
> `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`,
> `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`,
> `LTL`, `LVL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRO`,
> `MUR`, `MVR`, `MWK`, `MXN`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`,
> `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RMB`,
> `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`,
> `SLL`, `SOS`, `SRD`, `STD`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`,
> `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `UYI`, `UYU`, `UZS`,
> `VEF`, `VND`, `VUV`, `WON`, `WST`, `XAF`, `XAG`, `XAU`, `XCD`, `XOF`, `XPD`,
> `XPF`, `XPT`, `XSU`, `YER`, `ZAR`, `ZMK`, `ZWL`.
>
> **balance** `object`
>
> The statement's draw balance after the call; null when it has none.
>
> **object properties**
>
> **opening\_balance** `number`
>
> Opening balance carried over from the previous period.
>
> **balance\_override** `number`
>
> Opening balance set manually (overwrite), which detaches it from the
> previous period; null if not overridden. When set, this is the figure
> the draw is taken from.
>
> **drawn\_value** `number`
>
> The draw applied this period — the part of the balance recovered against
> this statement's commissions.
>
> **manually\_set** `boolean`
>
> True when the balance was entered or edited by hand.
>
> **balance\_after\_draw** `number`
>
> Balance left once this period's draw is applied — the opening balance
> (or its override) minus drawn\_value.