update_quota_values - Qobra public API documentation

Set, change or clear target values of one quota, for one or more users. Returns the changes made. Only the cells listed are written: a user or a period left out keeps its value, so this adjusts the grid, never replaces it. Read the current values with list_quota_values first when the change is relative to them. Pass value: null to clear a cell. On a value synchronized from an integration, null cancels the manual overwrite and brings the synchronized value back instead. The call is all or nothing: an unknown user, a period not in the quota’s frequency format, a user or a period listed twice, a currency the user cannot hold, or more than the cap refuses the whole call before anything is written. A call writes at most 100 values, all users together, and a currency change also counts the user’s other values it rewrites. An archived quota is refused, through a view too. Restoring it takes full access to quotas: call archive_quota with archived false. Without that access, ask someone who has it. Statements are not recalculated by this call, just as when a target is edited in the web app. To refresh them, call recalculate_statements on the users and the periods written. The quota’s environment (live or a sandbox) is the one the quota lives in. Without full write access to quotas, write through a view of the quota shared with you with edit rights, passed as view_id: only the users its filter holds can be written. The views of the returned quota have a null access: get_quota says who can read a view. Requires write permission on quotas, or a view shared with edit rights. 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 quota, from list_quotas or create_quota, a sandbox’s quota included.

object[]

required

The targets to write, grouped by user: at most 100 values per call, all users together.

Show object properties

string

required

Id or email of the user, as a user reference carries them.

string

Currency of this user’s amount targets, as a code (EUR, USD…). It applies to every value this user has on the quota, not only to the ones sent here. Omit it to keep the user’s current currency; ignored on a percentage or float quota.

object[]

required

The cells to write for this user, one per period.

Show object properties

string

required

Period of the target, in the quota’s own frequency format: YYYY-MM (monthly), YYYY-QX (quarterly), YYYY-SX (semesterly) or YYYY (annually).

number

required

The target, in the unit list_quota_values returns. null clears it — on a value synchronized from an integration, null cancels the manual overwrite and brings the synchronized value back instead, since a synchronized value is never deleted.

string

Id of one of the quota’s views, to write through. Required when your write access comes from shared views (only users its filter holds can be written); ignored with full write access.

Example

{
  "quota_id": "66a0b1c2d3e4f50012345678",
  "values": [
    {
      "user_id": "66a0b1c2d3e4f50012340001",
      "currency": "EUR",
      "values": [
        { "period": "2026-10", "value": 50000 },
        { "period": "2026-11", "value": 55000 }
      ]
    },
    {
      "user_id": "66a0b1c2d3e4f50012340002",
      "values": [{ "period": "2026-10", "value": null }]
    }
  ]
}

Response

Body

object

Show object properties

string

Deep link to open this quota in the Qobra web app.

string

Unit of the target: amount (has a currency), percentage, or float (plain number). One of: amount, percentage, float.

string

The period one target covers. A value’s period is written at this granularity (2026-03, 2026-Q1, 2026-S1, 2026).

string

Default currency of amount targets: ‘company’, ‘user’ (each user’s payment currency) or ‘calculation’ (the user’s calculation currency). A target with its own currency overrides it. Meaningless for a percentage or float quota. One of: company, user, calculation.

boolean

object[]

The quota views the caller may query for this quota’s values — pass one’s id as view_id to list_quota_values to narrow the rows. Empty when none is relevant.

Show object properties

string

object

Who can read this view, as roles and users with the level each holds. Resolved only by get_quota, get_data_table, get_identity and get_report (on a report’s own access), and only for callers who may share the resource. Null means not asked for or not yours to see, never an empty roster: a caller who may see it and finds nobody gets empty roles and users. get_identity lists the roles that reach every view through their access to the whole category once on the resource (category_roles), not on each view: there a role appears in roles only for the share it holds on this view, with its shared_access.

Show object properties

object[]

Show object properties

object

Show object properties

string

boolean

string

The level this role holds on the whole resource category, which reaches every view of it without a share — read (view it), write (edit and re-share it) or delete (also remove it), each level including the ones before it. Null when the role only got this view through a share. One of: read, write, delete.

string

The level granted to this role on this view specifically — read (view it), write (edit and re-share it) or delete (also remove it), each level including the ones before it. Null when the role reaches the view through its category access rather than a share. One of: read, write, delete.

object[]

Show object properties

object

Show object properties

string

The level this view is shared with the user at, individually, on top of whatever their role already grants — read (view it), write (edit and re-share it) or delete (also remove it), each level including the ones before it. One of: read, write, delete.

object[]

Every cell this call changed; a cell sent at its current value is not listed, so empty means nothing changed.

Show object properties

any

The value after this call; null when the cell was cleared.

string

Currency code of the value, only for an amount quota.

string

Deep link to the quota (a value has no page of its own).

object

Show object properties

string

What happened to the cell: created (it was empty), updated (new value), cleared (the value was removed), or overwrite_cancelled (a manual overwrite of a synchronized value was dropped, bringing the synchronized value back). One of: created, updated, cleared, overwrite_cancelled.

any

The value before this call; null when the cell was empty.

​Parameters

​Example

​Response

Parameters

Example

Response