update_statement_payments - Qobra public API documentation

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 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 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. 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

Body

string

required

Id of the statement to adjust — the id list_statements returns.

object[]

Manual payment lines to add, change or remove. At most 50 per call. Omit it to leave the lines as they are.

Show object properties

string

Id of the manual payment line to change or remove, a payment_id get_statement lists. Omit it to add a new line.

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.

number | null

required

The amount, in the statement’s calculation currency; negative to deduct. null removes the line.

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.

string

A comment kept with the change in the statement’s activity.

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.

Show object properties

number | null

required

The amount, in the statement’s calculation currency. null removes the manual value and brings the automatic one back.

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.

string

A comment kept with the change in the statement’s activity.

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.

Show object properties

number | null

required

The amount, in the statement’s calculation currency. null removes the manual value and brings the automatic one back.

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.

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:

{
  "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

Body

string

Deep link to the statement in the Qobra web app.

object[]

One row per manual payment sent, in the order sent.

Show object properties

string

number

The amount sent; null when the line was removed.

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.

object

What became of the draw; null when it was not sent.

Show object properties

number

The amount sent; null when it asked for the automatic value back.

string

object

What became of the carried balance; null when it was not sent.

Show object properties

number

The amount sent; null when it asked for the automatic value back.

string

number

Net amount to be paid out on the statement after the call, in currency: its lines, manual payments and draw together.

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.

object

The statement’s draw balance after the call; null when it has none.

Show object properties

number

Opening balance carried over from the previous period.

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.

number

The draw applied this period — the part of the balance recovered against this statement’s commissions.

boolean

True when the balance was entered or edited by hand.

number

Balance left once this period’s draw is applied — the opening balance (or its override) minus drawn_value.

​Parameters

​Example

​Response

Parameters

Example

Response