update_compensation - Qobra public API documentation

Update a compensation: rename it, change its cadence or its window, move it to another plan, publish or unpublish it, or schedule its publication for a later day. Pass at least one argument beside compensation_id. An edit (name, cadence, window) lands in one audit entry. What already matches changes nothing, so the same call can be sent twice. Which environment the compensation lives in comes from the compensation itself, so one you can’t access reads exactly like one that doesn’t exist — one living in a sandbox you may not read included. There is no sandbox_id argument on this tool for the same reason. 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.

Edit a compensation

name renames the compensation.
calculation_trigger changes its cadence.
dates_range bounds it to a window of days (YYYY-MM-DD), as the web app takes it. Send both start_date and end_date as empty strings to make it recurring again.

{
  "compensation_id": "6650f1c2a4b3e9d0f1a2b3c4",
  "status": "draft",
  "dates_range": { "start_date": "2027-01-01", "end_date": "2027-06-30" }
}

The cadence and the window change on a draft compensation only, as in the web app. To change them on a live compensation, pass status: "draft" in the same call to unpublish it first. A call carrying status: "live" applies the edit first, so the cadence it sets is what goes live.

How a window is calculated

A compensation bounded to a window is not paid period by period. Qobra calculates it once, over the records of the whole window, on the statement closing the period of its cadence that holds end_date. With EACH_MONTH, that is the period of end_date itself. The statements of the periods before carry no line for it. If the cadence does not calculate on that period, the compensation is never calculated. For example:

EACH_MONTH_EXCEPT_END_OF_QUARTER with an end_date in a quarter’s last month,
Q1–Q4 with an end_date outside that quarter, on the company’s fiscal calendar.

To pay every period over a limited time, leave the compensation recurring on a plan of its own, and bound the plan’s members to that time with the start_period and end_period of their attribution (create_plan, update_plan). An attribution is month-granular, and Qobra calculates any period of the cadence it touches over all of that period’s records. The limit is exact with EACH_MONTH, or when the attribution covers whole periods of the cadence. A quarterly compensation limited from February to April still pays the records of January, May and June. An attribution covers every compensation of its plan, so bounding the members of a shared plan ends all of them.

Publish, unpublish, or schedule

status and go_live_date are two different ways of publishing. Pass one per call.

status: "live" publishes now. Qobra applies the unpublished version stacked on the compensation when there is one (the version the Architect writes), and the compensation itself otherwise. Publishing now drops any scheduled publication.
status: "draft" unpublishes the compensation. Qobra discards the version stacked on top, and its scheduled publication with it.
go_live_date (YYYY-MM-DD) schedules the unpublished version to go live on a future day. It goes live two hours before the company’s daily statement recalculation, under your name. Pass an empty string to cancel a scheduled publication.

The first publication of a compensation recalculates the statements of every member of its plan over the compensation’s whole window. This can take a while.

Move to another plan

plan_id moves the compensation to another plan of the same environment. The target plan cannot be archived. Moving the compensation:

unpublishes it, so it lands in draft on the new plan,
discards the version stacked on it,
cancels a publication scheduled on it,
keeps on the new plan only the reporting metrics no compensation there feeds yet.

A move wins over a status or go_live_date sent in the same call, and so does a plan_id the compensation is already on. Qobra does not apply the status or go_live_date, and note in the result explains why. Send a second call with status: "live" and no plan_id to publish the compensation on its plan.

{
  "compensation_id": "6650f1c2a4b3e9d0f1a2b3c4",
  "plan_id": "6650f0aa1b2c3d4e5f6a7b8c"
}

Refusals

Qobra refuses the call before anything is written, with a message you can act on, when it sends:

a blank name,
a cadence or a window on a live compensation, without status: "draft" in the same call,
a window with only one day empty, or one that ends before it starts,
a target plan of another environment, or an archived one,
a publication of a compensation with no payment variable or an incomplete ranking,
any change to a compensation of an archived plan,
a publication of a compensation that feeds a reporting metric another live compensation of the plan already feeds,
a cadence, window, move, or status change while the Architect is still building the compensation,
a go_live_date that is not in the future,
a go_live_date on a live compensation with nothing to schedule.

Parameters

Body

string

required

Id of the compensation — the id get_plan lists, or the one create_compensation returned. The compensation also decides which environment it lives in, so there is no sandbox argument here.

string

New display name for the compensation. Omit to leave the current name as it is.

string

How often the compensation is calculated, on the company’s fiscal calendar. EACH_MONTH every month; EACH_MONTH_EXCEPT_END_OF_QUARTER every month but the one each quarter closes on; EACH_QUARTER, EACH_SEMESTER and EACH_YEAR at each period’s close; Q1–Q4 once a year, at that quarter’s close only. A compensation bounded to a window is calculated at most once: on the statement closing the period of its cadence that holds the window’s last day, and never when its cadence does not calculate on that period. Changes on a draft compensation only; omit to leave it as it is. One of: EACH_MONTH, EACH_MONTH_EXCEPT_END_OF_QUARTER, EACH_QUARTER, Q1, Q2, Q3, Q4, EACH_YEAR, EACH_SEMESTER.

object

The window the compensation applies to, as a pair of days: pass both to bound the compensation, both as empty strings to make it recurring again, or omit the pair to leave its window as it is. Changes on a draft compensation only. A windowed compensation is calculated once, at the end of its window: see How a window is calculated.

Show object properties

string

required

YYYY-MM-DD; the first day of the window. Pass both days as empty strings to make the compensation recurring again.

string

required

YYYY-MM-DD; the last day of the window, included.

string

Id of the plan to move the compensation to — the id list_plans returns, a plan of the same environment. Moving unpublishes the compensation. Omit to leave it on its plan.

string

live publishes the compensation — the unpublished version stacked on it when there is one, the compensation itself otherwise; draft unpublishes it. Omit to leave its status as it is. One of: live, draft.

string

YYYY-MM-DD; a future day on which the unpublished version goes live on its own. Pass an empty string to cancel a scheduled publication; omit to leave it as it is.

Response

Body

object

The compensation as get_plan now lists it, its status included: the published version, or the compensation itself while it was never published.

Show object properties

string

Deep link to open this compensation’s configuration in the Qobra web app.

string

boolean

True when the compensation has no window: it is calculated on each period of its cadence. False when it is bounded to one, from start_date to end_date, and calculated once at its end. See How a window is calculated.

string

YYYY-MM-DD; the first day of the compensation’s window, null when it is recurring.

string

YYYY-MM-DD; the last day of the compensation’s window, included, null when it is recurring.

string

How often the compensation is calculated, on the company’s fiscal calendar. EACH_MONTH every month; EACH_MONTH_EXCEPT_END_OF_QUARTER every month but the one each quarter closes on; EACH_QUARTER, EACH_SEMESTER and EACH_YEAR at each period’s close; Q1-Q4 once a year, at that quarter’s close only. A compensation bounded to a window is calculated at most once: on the statement closing the period of its cadence that holds the window’s last day, and never when its cadence does not calculate on that period.

string

“live” when the compensation is active on the plan; “draft” while it is still being edited and not yet applied.

string

The compensation’s own free-text note, as written on the plan; null when it carries none.

object[]

The reporting metrics this compensation feeds, one entry per metric flagged on one of its variables. Empty when this compensation feeds none — which says nothing about the plan on its own: a plan is missing from a report built on a metric only when none of its compensations feeds that metric.

Show object properties

string

One of: float, amount, percentage, string, picklist, multipicklist, bool, date, user, object, group, record_status.

object

The plan the compensation now hangs off — the target plan after a move.

Show object properties

string

boolean

True when a version is stacked on the published compensation, waiting to be published — status ‘live’ applies it.

string

YYYY-MM-DD; the day the pending version goes live on its own. Null when no publication is scheduled.

string

Why a status or go_live_date sent with a move was not applied: the move unpublished the compensation. Null otherwise.