Skip to main content
Queue the recalculation of some users’ statements over months, quarters or years, so they reflect the data as it stands now. The call returns at once with one row per user and month. 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 entry in periods for any number of users, or several entries for a single user; a quarter or a year counts as one entry. Several entries 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. Each row says what became of a user’s statement for a 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. A month with no statement has nothing to recalculate.
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.

Daily limit

A call that recalculates 5 users or more counts toward a limit of 5 such calls per user, per environment and per UTC day. The live environment and each sandbox are counted apart. The limit applies to every company, through the MCP and Qobra AI alike.
  • A call on fewer than 5 users is never counted.
  • Qobra counts the users actually recalculated, those whose row reads queued or unlicensed. A call where locked statements leave fewer than 5 users recalculated is not counted.
  • Past the limit, the call launches nothing. The error gives the time, in UTC, when you can recalculate again: midnight UTC the next day.
Do not split the users of a period into smaller calls to stay under the limit. This limit is counted apart from the one on trigger_import.

Parameters

Body

string[]
required
The periods to recalculate. A month (YYYY-MM), a quarter (YYYY-QX) or a year (YYYY); quarters and years follow the company’s fiscal calendar, as get_identity reports it. Several entries only when user_ids names a single user (a quarter or a year is one entry); the months between them are recalculated too.
string[]
required
The users whose statements to recalculate: ids from list_users or exact emails. Several only with a single entry in periods.
string
Id of a sandbox from list_sandboxes, to recalculate its statements instead of the live ones. Omit it for live. Never a name, never the live id.

Example

Recalculate two users over the third quarter:

Response

Body

integer
Statements the call covers: one per user and month.
object[]
Rollup of all total statements by outcome, 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; counts_by_outcome counts the rest, and list_statements reads their calculation_status.