> ## 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.

# Wage types

> Use the pay elements Intermezzo provides, or add your own.

Every pay line, whether in an employee's [standing pay](https://docs.intermezzo.ai/preview/gb/employees/compensation.md) or in a payroll run, names a **wage type** by its `wage_type_code`. The wage type says how HMRC treats the amount: whether it is taxable, which National Insurance applies, whether it counts for pension and minimum wage, and where it appears on the payslip.

Wage types come from two places:

* **The GB catalog.** Intermezzo maintains it, and every organization can use it. Catalog codes start with `UK-`, for example `UK-E-001` for basic salary. List them with [List Catalog Wage Types](https://docs.intermezzo.ai/api-reference/preview/great-britain/list-catalog-wage-types.md) (`GET /gb/wage-types`).
* **The organization's own types**, for pay elements the catalog doesn't cover. Their codes must not start with `UK-`.

When a pay line names a code, Intermezzo looks for it among the organization's own types first, then in the catalog.

## Add an organization wage type

[Create Wage Type](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-wage-type.md) takes the code and three satellites:

| Satellite | Holds |
| - | - |
| `core` | Name, description and category (`EARNINGS`, `DEDUCTIONS`, `BENEFITS`, …) |
| `treatment` | How HMRC treats the amount: tax, National Insurance class, pension, P11D, minimum wage |
| `computation` | Optional: how the amount is calculated from other codes, for example a percentage of basic pay |

```http Request theme={null}
POST /gb/organizations/{organization_id}/wage-types
```

```json Request body theme={null}
{
  "wage_type_code": "SHIFT-ALLOWANCE",
  "valid_from": "2026-04-06",
  "core": {
    "name": "Shift allowance",
    "description": "Allowance for night shifts",
    "category": "EARNINGS"
  },
  "treatment": {
    "taxable_status": "YES",
    "ni_class": "CLASS_1",
    "tax_timing": "ON_PAYMENT",
    "pension_status": "YES",
    "p11d_reportable_status": "NO",
    "payrolling_eligible_status": "NO",
    "nmw_treatment": "INCLUDED",
    "is_ae_qualifying": true,
    "is_proratable": true
  },
  "computation": null
}
```

The [API reference](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-wage-type.md) lists every `treatment` field; fields you leave out take the default shown there.

A new wage type starts as `DRAFT`. Payroll doesn't use it yet, so you can check the type and correct it before any payroll pays it.

## Check a computation

Before you write a `computation`, check it with [Dry-Run Wage Type Computation](https://docs.intermezzo.ai/api-reference/preview/great-britain/dry-run-wage-type-computation.md). It validates the computation as a `PUT` on that date would, explains it, and runs it against sample inputs you send. Nothing is written.

[Explain Wage Type Computation](https://docs.intermezzo.ai/api-reference/preview/great-britain/explain-wage-type-computation.md) describes the computation that applies on a date in words.

## Approve, deprecate and close

A wage type moves through these states. Each change is recorded in its read-only `lifecycle` satellite, from a `valid_from` date.

| Call | Effect |
| - | - |
| [Approve Wage Type](https://docs.intermezzo.ai/api-reference/preview/great-britain/approve-wage-type.md) | `DRAFT` → `APPROVED`. Payroll uses the type from `valid_from`. |
| [Deprecate Wage Type](https://docs.intermezzo.ai/api-reference/preview/great-britain/deprecate-wage-type.md) | `APPROVED` → `DEPRECATED`. Payroll stops using it from `valid_from`. |
| [Close Wage Type](https://docs.intermezzo.ai/api-reference/preview/great-britain/close-wage-type.md) | The record is finished and accepts no further changes |

```http Request theme={null}
POST /gb/organizations/{organization_id}/wage-types/{wage_type_id}/approve
If-Match: "<edition of the lifecycle>"
```

```json Request body theme={null}
{ "valid_from": "2026-04-06" }
```

Deprecate a type when the employer stops paying that element from a date: earlier payrolls keep it, later ones can't use it. Close a type only when the record is finished: after you deprecated it, and once no other type's `computation` reads it.

`If-Match` carries the `edition` of the `lifecycle` edition that `valid_from` falls in, read from [Get Lifecycle](https://docs.intermezzo.ai/api-reference/preview/great-britain/get-lifecycle.md).

Once a type is approved, payrolls may already have paid it, so:

* Its `category` can't change.
* A deprecation is refused while a live employee's [standing pay](https://docs.intermezzo.ai/preview/gb/employees/compensation.md) still uses the code on or after `valid_from`. Move those lines to another code first.
* A close is refused while another open wage type's `computation` reads the code.


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