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

# Compensation

> Set up salary and other pay that repeats every period.

An employee's standing pay is what is paid every period without being sent again: salary, a car allowance, a regular deduction. It lives in the employee's `compensation` satellite, so each change has a date range and history like any other satellite (see [Hubs, satellites and editions](https://docs.intermezzo.ai/preview/concepts/editions.md)).

Use standing pay for amounts that repeat unchanged every period. Amounts that change from period to period, such as overtime, a bonus or a one-off payment, are sent with the pay run instead; a guide to pay runs follows in a later release. Whether your organization uses standing pay at all, or sends all pay with each pay run, is agreed when Intermezzo sets up its payroll. Ask us if you're not sure.

## Set standing pay

Send `compensation` when you [create the employee](https://docs.intermezzo.ai/preview/gb/employees/create.md), or later with [Create Compensation Edition](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-compensation-edition.md). Its first `PUT` sends `If-None-Match: *` (see [Changing data](https://docs.intermezzo.ai/preview/concepts/changing-data.md#write-a-satellite-for-the-first-time)).

```http Request theme={null}
PUT /gb/organizations/{organization_id}/employees/{employee_id}/compensation
If-None-Match: *
```

```json Request body theme={null}
{
  "valid_from": "2026-04-06",
  "valid_to": "9999-12-31",
  "earnings": [
    {
      "external_ref": "SALARY",
      "wage_type_code": "UK-E-001",
      "earning_type": "AMOUNT",
      "amount": "42000.00",
      "earning_frequency": "YEAR",
      "is_lumpsum": false,
      "sacrificed_amount": null
    }
  ],
  "benefits": [],
  "deductions": [],
  "reimbursements": []
}
```

The satellite holds four lists. Send all four; an empty list means none.

| List | Each line holds |
| - | - |
| `earnings` | `amount` per `earning_frequency` (`YEAR`, `MONTH`, `WEEK`, …), and `sacrificed_amount` for the part given up under salary sacrifice |
| `benefits` | The benefit's `amount`, and the amounts that matter under optional remuneration arrangements: `cash_alternative_amount`, `foregone_amount`, `make_good_amount` |
| `deductions` | `amount`, and `sacrificed_amount` for a pre-tax salary sacrifice |
| `reimbursements` | `amount` |

A benefit in kind, such as a company car, is sent as the value you have already worked out for it. Intermezzo doesn't calculate the value from details such as the car's list price or CO2 emissions.

Every line names a `wage_type_code`: a code from the GB catalog or one of the organization's own [wage types](https://docs.intermezzo.ai/preview/gb/organization/wage-types.md). The wage type decides how the line is taxed. An unknown code returns `404 WAGE_TYPE_NOT_FOUND`.

`external_ref` on a line is your own key for it, so you can match lines across changes. Send `null` if you don't need it.

## Change standing pay

A pay rise is a `PUT` from the date it applies, with the whole satellite: all four lists, including the lines that didn't change.

```http Request theme={null}
PUT /gb/organizations/{organization_id}/employees/{employee_id}/compensation
If-Match: "<edition>"
```

```json Request body highlight={2,9} theme={null}
{
  "valid_from": "2027-01-01",
  "valid_to": "9999-12-31",
  "earnings": [
    {
      "external_ref": "SALARY",
      "wage_type_code": "UK-E-001",
      "earning_type": "AMOUNT",
      "amount": "45000.00",
      "earning_frequency": "YEAR",
      "is_lumpsum": false,
      "sacrificed_amount": null
    }
  ],
  "benefits": [],
  "deductions": [],
  "reimbursements": []
}
```

The `PUT` returns `200` with the new edition. Payrolls for periods from 1 January pay the new salary; earlier periods keep the old one.

* A change can go back at most one tax year (`400 COMPENSATION_EFFECTIVE_DATE_TOO_OLD`).
* A backdated change in a period that was already paid is paid as a retrospective change in the next payroll.
* To stop a line, leave it out of the lists from the date it ends.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.