Introduction

The /positions entity has access to payrollSetting (Position Payroll Settings /position-payroll-settings ) and it will reference the current active effective date delineated Employee Pay Rate (Position Pay Settings /position-pay-settings ), via one relation list that can be included (payrollSetting) and one integer for reference (payrollSetting.currentEffectivePaySettingId).

Payroll Settings Relation via Positions

[GET] /positions/382?include=payrollSetting

{
       "name": "AB Guard",
       "description": "",
       "customId": "UA-1",
       "status": "ACTIVE",
       "account": 687,
       "contract": 135,
       "nonBillable": false,
       "shiftMemo": "",
       "beginDate": "2022-08-01T00:00:00+00:00",
       "endDate": null,
       "breakRule": null,
       "taxClass": null,
       "payCodeLabel": 30,
       "taxLocation": null,
       "id": 382,
 ==>   "payrollSetting": {
           "payPositionRate": false,
           "positionHourlyRate": null,
           "holiday": "",
           "holidayRate": null,
           "holidayMultiplier": null,
           "holidayGroup": null,
           "payCode": 30,
           "payBreaks": "NONE",
  ==>      "currentEffectivePaySettingId": 397,
           "id": 382
       }
   }

As new effective pay rates enter their activation period, the ID in currentEffectivePaySettingsId will be updated.

If no effective pay rates are defined, then currentEffectivePaySettingId will be null.

Position Payroll Settings

payrollSetting can be called directly via /position-payroll-settings endpoint.

[GET]  /position-payroll-settings/382

{
   "payPositionRate": false,
   "positionHourlyRate": null,
   "holiday": "",
   "holidayRate": null,
   "holidayMultiplier": null,
   "holidayGroup": null,
   "payCode": 30,
   "payBreaks": "NONE",
   "currentEffectivePaySettingId": 397,
   "id": 382
}

And for the current effective pay setting, its direct call is via it’s ID (this example is WITHOUT an effective dated rate, which means the basic employee rate, which by default is a date of 1970-01-01, a linux epoch value).

Position Pay Settings

[GET] /position-pay-settings?id=397

{
   "positionPayroll": 382,
   "hourlyRateType": "EMPLOYEE",
   "hourlyRate": null,
   "effectiveDate": "1970-01-01T00:00:00+00:00",
   "id": 397
}

Next, here’s an example of the same position with a pending (to be effective as of 2024-04-11) pay rate (hourlyRate is not null, hourlyRateType is POSITION, and effectiveDate is not null):

[GET] /position-pay-settings?id=400

{
   "positionPayroll": 382,
   "hourlyRateType": "POSITION",
   "hourlyRate": 17.3,
   "effectiveDate": "2024-04-11T00:00:00+00:00",
   "id": 400
}

Positions that have a history of no effective dating, and then added effective dating for upcoming rates, you’ll see multiple records in position-pay-settings data for the same position. This is a good way of taking a look at how things have been and will become (position-pay-settings.positionPayroll == positions.id):

[GET] /position-pay-settings?positionPayroll=382

{
 ==>       "positionPayroll": 382,
           "hourlyRateType": "EMPLOYEE",
           "hourlyRate": null,
           "effectiveDate": "1970-01-01T00:00:00+00:00",
           "id": 397
       },
       {
==>        "positionPayroll": 382,
           "hourlyRateType": "POSITION",
           "hourlyRate": 17.3,
           "effectiveDate": "2024-04-11T00:00:00+00:00",
           "id": 400
}

Modifying Position Pay Settings

You may not create these settings from scratch because they'll be created automatically when the position gets created. You can modify them however. 

Another important thing to remember is that there are 4 fields that form a group pattern linked to the web application's user interface, so the pattern must be respected when setting the data or validation responses will block your progress. These are all detailed below. 

The 4 fields that should be modified together as a group are:

• holiday
• holidayRate
• holidayMultiplier
• holidayGroup

And they relate to the web application as 3 different patterns set by the Holiday Pay radio button choice:

Holiday pay: Do not pay holiday premiums

Group data to set:

• holiday: null
• holidayRate: null
• holidayMultiplier: null
• holidayGroup: null

PATCH /position-payroll-settings/382
NB: even though you set holiday to null, it will appear in responses after the patch and following GETs as holiday: ""

{
           "payPositionRate": true,
           "positionHourlyRate": 17.3,
           "holiday": null,
           "holidayRate": null,
           "holidayMultiplier": null,
           "holidayGroup": null,
           "payCode": 30,
           "payBreaks": "NONE"
}

Holiday pay: Rate multiplier

Group data to set:

• holiday: MULTIPLIER
• holidayRate: null
• holidayMultiplier: xx.xx
• holidayGroup: x

[PATCH] /position-payroll-settings/382

{
           "payPositionRate": true,
           "positionHourlyRate": 17.3,
           "holiday": "MULTIPLIER",
           "holidayRate": null,
           "holidayMultiplier": 1.9,
           "holidayGroup": 1,
           "payCode": 30,
           "payBreaks": "NONE"
}

Holiday pay: Fixed holiday rate

Group data to set:

• holiday: RATE
• holidayRate: xx.xx
• holidayMultiplier: null
• holidayGroup: x

[PATCH] /position-payroll-settings/382

{
           "payPositionRate": true,
           "positionHourlyRate": 17.3,
           "holiday": "RATE",
           "holidayRate": 12.95,
           "holidayMultiplier": null,
           "holidayGroup": 1,
           "payCode": 30,
           "payBreaks": "NONE"
}