Skip to main content
Recalculate the statements of some users over months, quarters or years, so they reflect the data as it stands now. Edits made through the other write tools reach no statement until it is recalculated. This covers create_record, update_record, split_record, update_quota_values and update_exchange_rates. Call this tool after them, with the users and the periods the change touches. A change in one month moves the months after it too, such as a carried balance or a year-to-date total. Cover every month it affects in the same call: Qobra computes the months of a call oldest first, while separate calls run side by side. A call takes one period for any number of users, or several periods for a single user. Several periods are recalculated as one span from the first month to the last, since a month reads its balance from the one before. When a change reaches past one period for several users, such as past a year end, call once per user with all their periods, never once per period. The recalculation runs in the background and the call returns at once, with what became of each user’s statement for each month:
  • queued: its recalculation is launched.
  • unlicensed: recalculated, but its compensations stay empty until the user gets a license.
  • locked: left as it is. A locked statement is never recalculated.
  • not_found: no statement you can see for this month.
To know when the recalculation is done, read the statements’ calculation_status with list_statements or get_statement. It reads need_refresh or calculating while it runs, and ready once the amounts are current. user_ids takes user ids or exact emails. Only users you can see can be named, and a month where you cannot see the statement reads not_found. Pass sandbox_id to recalculate a sandbox’s statements instead of the live ones. Available only where the Qobra write tools beta is enabled.

​
Parameters

Body

​
string[]
required
The periods to recalculate, each a month (YYYY-MM, e.g. 2026-03), a quarter (YYYY-QX, e.g. 2026-Q3) or a year (YYYY, e.g. 2026). Quarters and years follow the company’s fiscal calendar, as get_identity reports it. Several periods only when user_ids names a single user; the months between them are recalculated too.
​
string[]
required
The users whose statements to recalculate: the ids list_users returns, or their exact emails. As many as needed over one period; a single one when periods lists several.
​
string
Id of the sandbox whose statements to recalculate instead of the live ones — the id list_sandboxes returns. Omit it to recalculate the live statements, the company’s real compensation data. Only a sandbox id is accepted here — never a sandbox name, and never the live environment’s own id.

​
Example

Recalculate two users over the third quarter:

​
Response

Body

​
integer
Statements the call covers: one per user and month.
​
object[]
Per-outcome rollup of all total statements, listed in recalculations or not.
​
object[]
One row per user and month, the statements not queued first, then the queued ones, each in the order you passed the users, months oldest first. At most 100 rows: past them, counts_by_outcome still counts the rest, and list_statements reads their calculation_status.