Setting Employee Agreement Pay Rates (Date-Effective)

This guide explains how to create and manage employee agreements with date-effective pay rates using the Management V2 API.

Employee agreements define how an employee is paid, including their contract (award), classification level, and when pay rates take effect.

Base URL

/management/v2/employee-agreements

All endpoints require JWT authentication via the Authorization header.

Key Concepts

Employee Agreement

An employee agreement links an employee to their pay configuration. It defines:

• Employment contract (award / pay template)
• Pay rule (classification level)
• Pay period (weekly, fortnightly, etc.)
• Pay point (location)
• Effective date (when pay rates apply)
• Optional pay rule overrides (custom rates)

Effective Date

The startAt field controls when the agreement takes effect.

• Create a new agreement with a future startAt to schedule a pay change
• The existing agreement remains active until that date

Agreement History

Each agreement is part of a version chain:

• Tracked via employeeAgreementHistoryId
• Automatically updated when agreements are modified or superseded

Field Differences

Data Model

V2 Employee Agreement (API)

{
  "id": 12345,
  "employeeId": 999,
  "employmentContractId": 678,
  "payRuleId": 42,
  "payPeriodId": 1,
  "payPointId": 100,
  "startAt": "2026-07-01",
  "endAt": "",
  "isActive": true,
  "employeeAgreementHistoryId": 789
}

Field Mapping (UI → API)

Create an Employee Agreement

Assign a contract and pay rule to an employee.

Request

POST /management/v2/employee-agreements
Content-Type: application/json

{
  "employeeId": 999,
  "employmentContractId": 678,
  "payRuleId": 42,
  "payPeriodId": 1,
  "payPointId": 100,
  "startAt": "2026-07-01",
  "isActive": true
}

Required Fields

Schedule a Future Pay Change

To change pay rates in the future, create a new agreement with a future date.

Example

{
  "employeeId": 999,
  "employmentContractId": 678,
  "payRuleId": 55,
  "payPeriodId": 1,
  "payPointId": 100,
  "startAt": "2026-10-01",
  "isActive": true
}

Result:

• Existing agreement remains active until October 1
• New rates apply automatically from that date

Update an Agreement

Modify an existing agreement.

Request

PUT /management/v2/employee-agreements/{id}
Content-Type: application/json

{
  "employmentContractId": 700,
  "payRuleId": 60,
  "payPeriodId": 2,
  "payPointId": 200
}

Override Pay Rates

You can override contract rates using pay rule overrides (via the higher-level model).

Example

{
  "contract": {
    "id": "678",
    "overridePayRules": [
      {
        "payRuleId": "cr_abc123",
        "hourlyRate": 28.50
      }
    ]
  },
  "effectiveDate": "2026-07-01T00:00:00Z"
}

• Overrides the default contract rate
• Applies only to the specified pay rule

List Agreements

Retrieve agreements with filters.

Request

GET /management/v2/employee-agreements?filters=employeeId%3D999&limit=50

Supported Filters

• employeeId=999
• isActive=true

Get a Single Agreement

GET /management/v2/employee-agreements/{id}

Delete an Agreement

DELETE /management/v2/employee-agreements/{id}

Assign Award from Library (Enterprise)

Step 1: Create Contract from Award

POST /api/management/v2/employee/{employeeId}/set-award-from-library

{
  "countryCode": "au",
  "awardCode": "HIGA",
  "levelId": "ksuid_level_1",
  "overridePayRules": [
    {
      "id": "cr_base_rule_id",
      "hourlyRate": 25.41
    }
  ]
}

Step 2: Create Employee Agreement

POST /resource/EmployeeAgreement

{
  "Id": 0,
  "Active": true,
  "EmployeeId": 999,
  "Contract": 678,
  "PayPeriod": 1,
  "PayPoint": 100,
  "StartDate": "2026-07-01"
}

Configuration Behaviour

Defines how agreed hours are calculated for salaried employees:

Go Client Example

Create

params := ea.NewEmployeeAgreementV2ControllerCreateParams().
    WithContext(ctx)

result, err := client.EmployeeAgreementV2ControllerCreate(params, authInfo)

List

filters := []string{"employeeId=999", "isActive=true"}
limit := int32(50)

params := ea.NewEmployeeAgreementV2ControllerListParams().
    WithContext(ctx).
    WithFilters(filters).
    WithLimit(&limit)

result, err := client.EmployeeAgreementV2ControllerList(params, authInfo)

Update

params := ea.NewEmployeeAgreementV2ControllerUpdateParams().
    WithContext(ctx).
    WithID("12345")

result, err := client.EmployeeAgreementV2ControllerUpdate(params, authInfo)

Summary

• Use employee agreements to control pay configuration
• Use startAt for date-effective pay changes
• Create new agreements (don’t overwrite) to preserve history
• Use overrides for custom pay rates when needed