We’re automating merit increase processing through the Workday Compensation API and getting consistent failures with ‘invalid compensation plan reference’ errors. When updating worker compensation via API, the system returns an error saying the compensation plan is invalid, but the same plan works fine when processing manually through the UI.
Error response:
PUT /workers/{id}/compensation
{"planId": "MERIT_2024", "newSalary": 75000}
Error: Invalid compensation plan reference
The plan ID is correct (we can retrieve it via GET /compensationPlans), and the employee is eligible for merit increases according to our HR team. This is blocking our entire merit cycle automation affecting 300+ employees. Has anyone successfully automated compensation updates and dealt with plan eligibility validation through the API?
I’ve seen this error when the effective date of the compensation change doesn’t align with the plan’s eligibility rules. Workday validates that the effective date falls within an active plan period and that the employee meets eligibility criteria as of that date. The UI might auto-adjust dates to valid values, but the API requires you to send exactly valid dates. Check your compensation plan configuration for eligibility rules - there might be service length requirements, job profile restrictions, or supervisory org limitations that the API is enforcing. Also verify that the integration security group has permission to modify compensation for the specific plan and supervisory organizations involved.
The compensation plan reference needs to include more than just the plan ID. You need to specify the effective date and potentially the compensation element within the plan. The API is stricter about these references than the UI.
Beyond the effective date, you need to validate employee eligibility programmatically before attempting the update. The API won’t tell you WHY a plan is invalid for a worker, just that it is. We built a pre-validation step that checks: employee’s hire date meets minimum service requirements, employee’s job profile is in the eligible job families list, employee’s location/org is included in plan scope, and employee isn’t already at max compensation for their grade. This reduced our API failures by 90%.
Make sure the effective date matches exactly with the compensation plan’s active period. If your merit cycle starts April 1st but the plan becomes active April 15th, using April 1st will fail validation. Also check that you’re referencing the right plan version - compensation plans can have multiple active versions with different effective dates.