Lesson 5 — Maintaining GCC Social Rates: dated lines, never edited in place
This lesson is about the maintenance habit that keeps a payroll auditable, and it takes ten minutes a year to get right.
The obligation. Rates move on the home country's calendar rather than on yours. Saudi rates escalate every July and Bahrain's every January, so a rate that was correct when you configured it will be wrong on a predictable date. Nobody sends you a notice. This is a diary task, not an alert you can wait for.
The mental model. A rate is not a value stored on a country; it is a dated line that is in force for a range of payslip periods. The module resolves the rate by looking for the line whose effective date covers the payslip period being computed. That is why the register can hold several lines for the same country at once, and why a period with no covering line has no rate rather than a stale one.
The click path, and the one rule. Open Payroll › Configuration › GCC Social Rates. When a rate moves, add a new line with a later effective date and archive the old one. Never edit a line in place. Editing rewrites history: last year's payslips were computed on the old rate, and if the line that produced them now shows a different number, those payslips stop being explicable to an auditor, to the home authority, or to the employee who queries them.
The shipped rates are effective 2026-08-02 — the date they were captured — so a payslip period before 2 August 2026 has no rate in force and stops with the message No GCC social-security rate is configured for <country> effective <date>. That is not a defect. It is the register telling you it holds no evidence about a period it was never given. Add a line with the correct earlier effective date and the historic period computes.
Four steps whenever a rate changes, in this order:
- Capture the source first — the home authority's page or circular, the rate, the effective date, and the date you read it. This is what you will show when someone asks why a payslip used that number.
- Create a new line for that country with the new effective date and the new employer and employee rates. Do not touch the existing line.
- Archive the superseded line rather than deleting it. An archived line stays available to explain the payslips it produced; a deleted one does not.
- Recompute one payslip in a period before the change and one after, and confirm each picks up the rate you expect. Two payslips prove the boundary works in both directions.
The worked example. Here is what a correctly maintained register looks like for one country across three periods.
| Line | Effective from | Employer rate | Employee rate | The periods it serves |
|---|---|---|---|---|
| The line you add for history | the date the rate you hold took effect | the rate in force then | the rate in force then | payslip periods before 2 August 2026 |
| The shipped line | 2026-08-02 | 9% | 9% | payslip periods from 2 August 2026 until a later line exists |
| The line you add each July | the July date the new rate takes effect | the newly published rate | the newly published rate | payslip periods from that July onward |
The middle row is the only one that ships with the module. The other two are yours to add, and the first of them is the one most establishments discover late, on the day someone reruns a historic payslip and the register says it has nothing for that period.
The failure mode. Editing a rate in place because it is quicker, and archiving nothing. Six months later a payslip cannot be reproduced, and the difference between "the rate changed" and "someone changed the rate" is no longer visible in the record. Where an auditor can see the dated line that produced a figure, a rate change is a routine event. Where they cannot, it becomes a question about your controls.