> ## Documentation Index > Fetch the complete documentation index at: https://docs.hitaji360.com/llms.txt > Use this file to discover all available pages before exploring further. # Promotions > A promotion records an upward move for an employee who is already on the books — typically a new grade, position, or department with a pay rise. A promotion records an upward move for an employee who is already on the books — typically a new grade, position, or department **with a pay rise**. Like a transfer, it ends the current contract and opens a successor; unlike a transfer, it can also create a new salary structure assignment so the next payroll picks up the higher pay. Every change is captured as a before/after pair so you have a clean audit trail of exactly what moved. This page explains what a promotion is (and how it differs from a transfer), the fields it captures, its lifecycle and statuses, and how an applied promotion appears in the employee's Work History. **You'll find this at:** `/api/hr/employee-promotions` (API only — see *Current state* below) > ⚠️ **Current state:** Promotions are **not yet surfaced in the web app**. There is no Promote button, form, or list screen — the entire flow (create draft, submit, schedule, apply, cancel) is currently **API-only**. The one place a promotion does appear in the UI is the employee profile's **Work History** timeline, which shows applied promotions. Until a screen is built, promotions are created and managed by integrations or the API directly. Flagged for the team. > Hitaji 360 is **multi-business**. A promotion belongs to the same business as the employee's source contract and must match the active business context. It cannot move someone across businesses. *** ## Promotion vs transfer A **transfer** is a lateral move — department, position, manager, work location, or employment type — and is treated as a **no-pay-change** event (the existing salary is carried forward as-is). A **promotion** is the same kind of contract end-and-recreate, but it is built around a **pay change**. If you give it a new base salary, applying the promotion creates a fresh, submitted **salary structure assignment** on the new contract dated to the effective date, so the next payroll run pays the new amount. A promotion can also carry a new grade, position, or department alongside the pay rise. A promotion **without** a new base salary is a valid "title-only" promotion — it records the move (e.g. a grade change) but does **not** create a new salary assignment. *** ## How a promotion is created (the lifecycle) A promotion follows the same shape as the Employee Transfer doctype: 1. **Create** — a **Draft** record is created. The system reads the employee's current contract and active salary assignment so it can compute the before/after deltas. 2. **Submit** — on submit the record gets its document number and either: * **applies immediately** if the effective date is today or earlier, or * is marked **Scheduled** if the effective date is in the future, and a daily job (04:00 UTC) applies it on the day it falls due. 3. **Apply** — ends the source contract, creates the successor, creates the new salary assignment (if a new base salary was given), and writes the before/after history rows. The source contract must still be **active** at both submit and apply — you cannot promote someone whose contract has already ended. ### Fields | Field | Required | Notes | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- | | **businessId** | Yes | Must match the source contract's business **and** the active `X-Business-Id` context. | | **employeeId** | Yes | The employee being promoted. | | **employmentContractId** | Yes | The source (current) contract. Must belong to the employee. | | **effectiveDate** | Yes | `YYYY-MM-DD`. Drives the immediate-vs-scheduled decision. | | **newOrgUnitId** | No | Target department. | | **newOrgPositionId** | No | Target position. | | **newGradeLevel** | No | New grade label (free text, up to 50 chars). Recorded for audit even though grade isn't a contract field. | | **newBaseSalary** | No | New base pay; must be **greater than 0** when provided. Supplying this is what triggers the new salary assignment. | | **newVariableSalary** | No | New variable pay. | | **newSalaryStructureId** | No | Move the new assignment onto a specific salary structure. If omitted, the existing structure is reused with the new base. | | **reason** | No | Free text. | > **A salary-bump promotion needs a structure to attach to.** If you set a new base salary, the source contract must already have an active salary structure assignment to inherit from, **or** you must supply `newSalaryStructureId` explicitly. Otherwise the apply step is rejected with a clear error rather than guessing. ### Before/after details Each changed field is stored as a **promotion detail** row holding the property name, its current value, and its new value (for example *base: 1,000,000 → 1,500,000*). Only fields that actually change are recorded. These detail rows are what populate the *from → to* lines in Work History. *** ## Promotion statuses | Status | Meaning | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Draft** | Created but not submitted. Can be cancelled. | | **Scheduled** | Submitted with a future effective date; waiting for the daily job to apply it. Can still be cancelled. | | **Applied** | The contract change (and salary assignment, if any) has been written. **Cannot be cancelled** — reverse it with a counter-promotion (a demotion). | | **Failed** | The apply step raised an error; the record carries the error detail for manual remediation. | | **Cancelled** | Cancelled before it applied. | ### Cancelling A promotion can be cancelled only **before** it applies (Draft or Scheduled). Once **Applied**, the new contract and salary already exist, so you must issue a counter-promotion (demotion) rather than cancelling. *** ## How a promotion shows up in Work History The employee profile's **Work History** timeline builds its events from **applied** promotions (alongside contracts and transfers). An applied promotion appears as a **"Promoted"** entry on the effective date, with an expandable **Details** section listing each changed field as *from → to* (for example, *base: 1,000,000 → 1,500,000*, *orgPositionId: Officer → Senior Officer*). Promotions that are still Draft, Scheduled, Failed, or Cancelled do **not** appear in the timeline — only applied ones do. > 📷 *Screenshot: Work History timeline showing a "Promoted" event with its expanded before/after details — to be added.* *** ## Permissions | Action | Permission | | -------------------------------------------- | ---------- | | Create / submit / cancel / apply a promotion | `hr:write` | | View a promotion record | `hr:read` | *** ## Related * [Transfers](/hr/user/employees/transfers) — the lateral, no-pay-change sibling of a promotion * [The employee profile & its tabs](/hr/user/employees/employee-profile) — where the Work History timeline lives * [Employment records & contracts](/hr/user/employees/employment-and-contracts) — what a promotion ends and recreates * [Salary structures](/hr/user/payroll/salary-structures) — the structure a promotion's new salary assignment attaches to * [Running payroll](/hr/user/payroll/running-payroll) — how the new salary assignment is picked up