Skip to main content
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

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

​
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