> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# update_compensation

> Rename a compensation, change its cadence or window, move it to another plan, publish or unpublish it, or schedule its publication.

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.

```json theme={null}
{
  "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`](https://docs.qobra.co/mcp_documentation/tools/create_plan),
[`update_plan`](https://docs.qobra.co/mcp_documentation/tools/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.

```json theme={null}
{
  "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

> [accordion] Body
>
> **compensation\_id** `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.
>
> **name** `string`
>
> New display name for the compensation. Omit to leave the current name as it
> is.
>
> **calculation\_trigger** `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`.
>
> **dates\_range** `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](#how-a-window-is-calculated).
>
> **object properties**
>
> **start\_date** `string` *required*
>
> YYYY-MM-DD; the first day of the window. Pass both days as empty
> strings to make the compensation recurring again.
>
> **end\_date** `string` *required*
>
> YYYY-MM-DD; the last day of the window, included.
>
> **plan\_id** `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.
>
> **status** `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`.
>
> **go\_live\_date** `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

> [accordion] Body
>
> **compensation** `object`
>
> The compensation as get\_plan now lists it, its status included: the
> published version, or the compensation itself while it was never published.
>
> **object properties**
>
> **id** `string`
>
> **resource\_url** `string`
>
> Deep link to open this compensation's configuration in the Qobra web
> app.
>
> **name** `string`
>
> **recurring** `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](#how-a-window-is-calculated).
>
> **start\_date** `string`
>
> YYYY-MM-DD; the first day of the compensation's window, null when it is
> recurring.
>
> **end\_date** `string`
>
> YYYY-MM-DD; the last day of the compensation's window, included, null
> when it is recurring.
>
> **period** `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.
>
> **status** `string`
>
> "live" when the compensation is active on the plan; "draft" while it is
> still being edited and not yet applied.
>
> **description** `string`
>
> The compensation's own free-text note, as written on the plan; null when
> it carries none.
>
> **flagged\_metrics** `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.
>
> **object properties**
>
> **id** `string`
>
> **name** `string`
>
> **type** `string`
>
> One of: `float`, `amount`, `percentage`, `string`, `picklist`,
> `multipicklist`, `bool`, `date`, `user`, `object`, `group`,
> `record_status`.
>
> **plan** `object`
>
> The plan the compensation now hangs off — the target plan after a move.
>
> **object properties**
>
> **id** `string`
>
> **name** `string`
>
> **resolved** `boolean`
>
> **has\_unpublished\_version** `boolean`
>
> True when a version is stacked on the published compensation, waiting to be
> published — status 'live' applies it.
>
> **scheduled\_go\_live\_date** `string`
>
> YYYY-MM-DD; the day the pending version goes live on its own. Null when no
> publication is scheduled.
>
> **note** `string`
>
> Why a status or go\_live\_date sent with a move was not applied: the move
> unpublished the compensation. Null otherwise.