Employee Payroll Deduction Life Cycle
Guide showing various states of an employee's payroll deductions throughout a plan year and how changes are reflected on the API.
This page will walk through the employee life cycle of payroll deductions as they go through various changes throughout the year.
Change Log
| Document Version | Date Modified | Content Changed |
|---|---|---|
| V1 | 2/22/2019 | Initial creation |
1. Introduction
As a payroll vendor, the typical PlanSource fields that should be tracked are the following:
- id/subscriber_code - Method of identifying the employee (primary key). Vendor should use same ID they are using for pushing demographic data.
- benefit_lookup_code - PlanSource standardized deduction code. This value is unique to each benefit available in PlanSource but standardized meaning it does NOT change from client to client. E.G: Medical = medical, dental = dental, etc...
- subscriber_premium - EE per pay period calculated premium amount.
- org_premium - ER paid per pay period calculated premium amount.
- change_effective_date - The date the deduction/coverage becomes effective.
- current - Used to find current active record.
2. Initial Scenario
Employee Payroll Test1 has just been hired within the company on 7/10/2018. The client is configured in PlanSource to have an employee's coverage start date be the 1st of the month after their hire date, in this case 8/1/2018. Their demographic data is as follows:
{
"status": "success",
"errors": [],
"data": {
"links": [
{
"href": "/admin/subscriber/Payroll_1?is_custom_id=true",
"rel": "self"
}
],
"id": 19147266,
"subscriber_code": "Payroll_1",
"first_name": "Payroll",
"last_name": "Test1",
"middle_name": "E",
"address_1": "123 Main Street",
"address_2": "Apartment 54",
"city": "Jacksonville",
"state": "FL",
"zip_code": "32777",
"country": "United States",
"home_phone": "4075553333",
"work_phone": "4075552222",
"cell_phone": "4075551111",
"gender": "M",
"hire_date": "2018/07/10",
"birthdate": "1984/02/22",
"ssn": "555724484",
"termination_date": null,
"union_code": "LOCAL56",
"employment_level": "FT",
"pay_rate": "10.0",
"pay_type": null,
"org_payroll_id": 111106,
"employee_number": "135538",
"public_id": 997306,
"marital_status": "U",
"division": "A",
"location": "FLORIDA",
"org_class": "SALARIED",
"business_title": "Org Tester",
"udef_1": null,
"udef_2": null,
"udef_3": null,
"udef_4": null,
"udef_5": null,
"udef_6": null,
"udef_7": null,
"udef_8": null,
"udef_9": null,
"udef_10": null,
"udef_11": null,
"udef_12": null,
"udef_13": null,
"udef_14": null,
"udef_15": null,
"udef_16": null,
"udef_17": null,
"udef_18": null,
"udef_19": null,
"udef_20": null,
"ee_code": null,
"benefit_company": null,
"original_hire_date": "2018/07/10",
"seniority_date": null,
"employment_status": null,
"employment_status_starts_on": null,
"employee_type": null,
"current_salary_effective_on": "2018/03/10",
"current_salary": "450500.0",
"benefit_deduction_group": null,
"highly_compensated": null,
"vip": null,
"fmla": null,
"name_suffix": null,
"benefits_start_date": "2018/07/10",
"test_employee": false,
"is_voluntary_termination": false,
"hide_from_payroll": false,
"termination_reason_id": null,
"shareholder": false,
"owner": false,
"hours_per_week": 40,
"is_smoker": null,
"county": null,
"udef_21": null,
"udef_22": null,
"udef_23": null,
"udef_24": null,
"udef_25": null,
"udef_26": null,
"udef_27": null,
"udef_28": null,
"udef_29": null,
"udef_30": null,
"email": "[email protected]",
"user_name": "INTEGRATIONTEST_1",
"email2": "",
"preferred_locale": null
}
}
3. Initial Enrollment
For this example, the employee does not have any previous enrollment history in PlanSource. The employee goes through their New Hire Enrollment. This employee does not have any benefit eligible family members and elects a Medical plan (Open Access 90/10) for "Employee Only."
The payroll integration system wants to obtain the employee's deduction data. They make a call to the PlanSource payroll subscriber endpoint for this employee to obtain this information. The following call is made:
Start Date & End Date
When making calls to the Payroll API, it requires a start_date & end_date to be supplied (YYYY-MM-DD). These dates set the range for pulling deduction information. In order for a record to be returned, the coverages updated_at date must fall within this range.
The updated_at date must fall within the start_date and end_date range. Any records with an updated_at date that are equal to or greater than the start_date will be returned. Any records with an updated_at date that is less than the end_date (NOT equal to it) will be returned.
A payload is returned containing all of the employee's elections made during their enrollment. For simplicity, below is only the employee's current medical election. When looking for the active record in PlanSource, it will always be denoted where "current = Y."
{
"id": 19147266,
"subscriber_code": "Payroll_1",
"first_name": "Payroll",
"middle_name": "E",
"last_name": "Test1",
"ssn": "555-72-4484",
"subscriber_status": null,
"subscriber_pay_frequency": "Biweekly (26 per year)",
"subscriber_total_paydays": 26,
"organization_id": 153602,
"org_plan_year_starts": "2018/08/01",
"org_plan_year_ends": "2019/07/31",
"benefit_name": "Medical",
"benefit_lookup_code": "medical",
"plan_name": "Open Access 90/10",
"coverage_level": "Employee Only",
"subscriber_premium": "101.58",
"org_premium": "184.62",
"imputed_income": "0.0",
"subscriber_pretax_premium": "0.0",
"subscriber_posttax_premium": "0.0",
"tax_treatment": "pretax",
"volume": "0.0",
"org_fsa_amount": "0.0",
"original_effective_date": "2018-08-01T00:00:00+00:00",
"change_effective_date": "2018-08-01T00:00:00+00:00",
"dp_sub_imputed_income": "0.0",
"dp_org_imputed_income": "0.0",
"plan_payroll_mapping_code": "",
"plan_group_number": null,
"plan_partner_code_1": "",
"plan_partner_code_2": "",
"current": "Y",
"updated_at": "2019-02-21T21:43:57+00:00",
"created_at": "2019-02-21T21:43:57+00:00",
"benefit_company": null
},
Example Results:
In the payload above for medical where current = Y, the employee has a deduction amount of $101.58 and a future effective date of 8/1/2018.
4. Use Cases During Open Enrollment Window
Payroll Deduction Calls During Open & New-Hire Enrollment
It should be known that pulling payroll deduction data for an employee while the employee's open enrollment or new-hire enrollment windows remain open can result in a strange situation where PlanSource will have a deduction that has a termination date that occurs prior to the effective date. This typically occurs due to how clients handle coverage start dates (1st of the month following benefit eligible start date....in the example 8/1/2018) and termination dates (Last of the month....in the example 7/31/2018).
Continuing the same scenario from above. Payroll Test1 decides later during their enrollment window that they made a mistake and no longer want medical coverage through their employer. The employee goes back into enrollment and elects the Decline medical plan.
What you will notice when calling the PlanSource API is a change in records. The previous original election detailed in the previous step
Example Results:
After electing the decline, the payload below will flip the previous election's current value to "N" and the current decline election will be set to "Y."
You will then notice the scenario described in the caution call-out above where a termination date occurs prior to the actual effective date of coverage.
"change_effective_date": "2018-08-01T00:00:00+00:00", "termination_date": "2018/07/31",
Deduction Processing
It is important to make sure the payroll system can process/handle a deduction stop in this scenario.
{
"id": 19147266,
"subscriber_code": "Payroll_1",
"first_name": "Payroll",
"middle_name": "E",
"last_name": "Test1",
"ssn": "555-72-4484",
"subscriber_status": null,
"subscriber_pay_frequency": "Biweekly (26 per year)",
"subscriber_total_paydays": 26,
"organization_id": 153602,
"org_plan_year_starts": "2018/08/01",
"org_plan_year_ends": "2019/07/31",
"benefit_name": "Medical",
"benefit_lookup_code": "medical",
"plan_name": "Decline",
"coverage_level": "Decline",
"subscriber_premium": "0.0",
"org_premium": "0.0",
"imputed_income": "0.0",
"subscriber_pretax_premium": "0.0",
"subscriber_posttax_premium": "0.0",
"tax_treatment": "posttax",
"volume": "0.0",
"org_fsa_amount": "0.0",
"original_effective_date": "2018-08-01T00:00:00+00:00",
"change_effective_date": "2018-08-01T00:00:00+00:00",
"termination_date": "2018/07/31",
"termination_reason": "Subscriber voluntarily waived coverage",
"dp_sub_imputed_income": "0.0",
"dp_org_imputed_income": "0.0",
"plan_payroll_mapping_code": null,
"plan_group_number": null,
"plan_partner_code_1": null,
"plan_partner_code_2": null,
"current": "Y",
"updated_at": "2019-02-22T05:21:52+00:00",
"created_at": "2019-02-21T21:43:57+00:00",
"benefit_company": null
},
{
"id": 19147266,
"subscriber_code": "Payroll_1",
"first_name": "Payroll",
"middle_name": "E",
"last_name": "Test1",
"ssn": "555-72-4484",
"subscriber_status": null,
"subscriber_pay_frequency": "Biweekly (26 per year)",
"subscriber_total_paydays": 26,
"organization_id": 153602,
"org_plan_year_starts": "2018/08/01",
"org_plan_year_ends": "2019/07/31",
"benefit_name": "Medical",
"benefit_lookup_code": "medical",
"plan_name": "Open Access 90/10",
"coverage_level": "Employee Only",
"subscriber_premium": "101.58",
"org_premium": "184.62",
"imputed_income": "0.0",
"subscriber_pretax_premium": "0.0",
"subscriber_posttax_premium": "0.0",
"tax_treatment": "pretax",
"volume": "0.0",
"org_fsa_amount": "0.0",
"original_effective_date": "2018-08-01T00:00:00+00:00",
"change_effective_date": "2018-08-01T00:00:00+00:00",
"dp_sub_imputed_income": "0.0",
"dp_org_imputed_income": "0.0",
"plan_payroll_mapping_code": "",
"plan_group_number": null,
"plan_partner_code_1": "",
"plan_partner_code_2": "",
"current": "N",
"updated_at": "2019-02-21T21:43:57+00:00",
"created_at": "2019-02-21T21:43:57+00:00",
"benefit_company": null
},
5. Life Event with Coverage Tier Change
This scenario will detail an employee going from a medical employee only election to a marriage life event and updating their medical coverage to employee + spouse.
For this scenario we are going to use an employee named Payroll Test2. All other demographic data will remain identical to Payroll Test1, with exception of key PII information that would be unique to a person. This employee is also enrolled in the 90/10 medical plan with a deduction amount of $101.58 and a future effective date of 8/1/2018 prior to the life event.
In this scenario the employee is submitting a life event for marriage with an effective date of 2/1/2019.
{
"id": 19147778,
"subscriber_code": "Payroll_2",
"first_name": "Payroll",
"middle_name": "E",
"last_name": "Test2",
"ssn": "555-72-4485",
"subscriber_status": null,
"subscriber_pay_frequency": "Biweekly (26 per year)",
"subscriber_total_paydays": 26,
"organization_id": 153602,
"org_plan_year_starts": "2018/08/01",
"org_plan_year_ends": "2019/07/31",
"benefit_name": "Medical",
"benefit_lookup_code": "medical",
"plan_name": "Open Access 90/10",
"coverage_level": "Employee + Spouse",
"subscriber_premium": "226.06",
"org_premium": "184.62",
"imputed_income": "0.0",
"subscriber_pretax_premium": "0.0",
"subscriber_posttax_premium": "0.0",
"tax_treatment": "pretax",
"volume": "0.0",
"org_fsa_amount": "0.0",
"original_effective_date": "2018-08-01T00:00:00+00:00",
"change_effective_date": "2019-02-01T00:00:00+00:00",
"dp_sub_imputed_income": "0.0",
"dp_org_imputed_income": "0.0",
"plan_payroll_mapping_code": "",
"plan_group_number": null,
"plan_partner_code_1": "",
"plan_partner_code_2": "",
"current": "Y",
"updated_at": "2019-02-22T05:59:19+00:00",
"created_at": "2019-02-22T05:54:14+00:00",
"benefit_company": null
},
{
"id": 19147778,
"subscriber_code": "Payroll_2",
"first_name": "Payroll",
"middle_name": "E",
"last_name": "Test2",
"ssn": "555-72-4485",
"subscriber_status": null,
"subscriber_pay_frequency": "Biweekly (26 per year)",
"subscriber_total_paydays": 26,
"organization_id": 153602,
"org_plan_year_starts": "2018/08/01",
"org_plan_year_ends": "2019/07/31",
"benefit_name": "Medical",
"benefit_lookup_code": "medical",
"plan_name": "Open Access 90/10",
"coverage_level": "Employee Only",
"subscriber_premium": "101.58",
"org_premium": "184.62",
"imputed_income": "0.0",
"subscriber_pretax_premium": "0.0",
"subscriber_posttax_premium": "0.0",
"tax_treatment": "pretax",
"volume": "0.0",
"org_fsa_amount": "0.0",
"original_effective_date": "2018-08-01T00:00:00+00:00",
"change_effective_date": "2018-08-01T00:00:00+00:00",
"dp_sub_imputed_income": "0.0",
"dp_org_imputed_income": "0.0",
"plan_payroll_mapping_code": "",
"plan_group_number": null,
"plan_partner_code_1": "",
"plan_partner_code_2": "",
"current": "N",
"updated_at": "2019-02-22T05:54:14+00:00",
"created_at": "2019-02-22T05:54:14+00:00",
"benefit_company": null
},
Example Result
The previous employee only coverage will update to current = "N" and new coverage will be created with current = "Y." A change can be detected by looking at the change_effective_date becoming the 2018-02-01, and the subscriber_premium amount increasing to $226.06 from the previous $101.58
6. Employee Termination
In the event of an employee termination, the only field that will change is that of the termination_date field on the coverage. If a record is found with a termination date not equal to null, a deduction stop should be applied with the termination date of the new record marked as current = "Y."
{
"id": 19148290,
"subscriber_code": "Payroll_3",
"first_name": "Payroll",
"middle_name": "E",
"last_name": "Test3",
"ssn": "555-72-4486",
"subscriber_status": null,
"subscriber_pay_frequency": "Biweekly (26 per year)",
"subscriber_total_paydays": 26,
"organization_id": 153602,
"org_plan_year_starts": "2018/08/01",
"org_plan_year_ends": "2019/07/31",
"benefit_name": "Medical",
"benefit_lookup_code": "medical",
"plan_name": "Open Access 90/10",
"coverage_level": "Employee Only",
"subscriber_premium": "101.58",
"org_premium": "184.62",
"imputed_income": "0.0",
"subscriber_pretax_premium": "0.0",
"subscriber_posttax_premium": "0.0",
"tax_treatment": "pretax",
"volume": "0.0",
"org_fsa_amount": "0.0",
"original_effective_date": "2018-08-01T00:00:00+00:00",
"change_effective_date": "2018-08-01T00:00:00+00:00",
"dp_sub_imputed_income": "0.0",
"dp_org_imputed_income": "0.0",
"plan_payroll_mapping_code": "",
"plan_group_number": null,
"plan_partner_code_1": "",
"plan_partner_code_2": "",
"current": "Y",
"updated_at": "2019-02-22T06:43:39+00:00",
"created_at": "2019-02-22T06:42:12+00:00",
"benefit_company": null,
"termination_date": "2019/02/28",
"termination_reason": "Employment is terminated (voluntarily or involuntarily) in a manner that does not make the employee ineligible for COBRA (if applicable)."
},
7. New Plan Year (Coming Soon)
Details on how to treat new plan years coming soon.
8. Conclusion
This guide contains the typical scenarios encountered when using the PlanSource Payroll API.
Vendors using the Payroll Deduction API should use a combination of change_effective_date, subscriber_premium, and any other relevant data contained on the payroll API as a method of determining when a change occurs by comparing the record where current = "Y" against what is currently stored in the payroll system. If any change is detected, the payroll system should make the proper update of the current deduction.
It's important to remember that a record can be marked as current = "Y" and be a future dated deduction. The current field represents which deduction record is the most recent active record in PlanSource.
For payroll systems that must stop a deduction prior to making an update. When comparing the a deduction record to detect a change, if a change is found that is NOT a termination (E.G. marriage life event resulting in coverage tier change) the payroll vendor should use the new deduction change_effective_date - 1 day to determine the previous deduction stop date. Please see below for an example:
If the new election does have a termination date that is not equal to null, the logic below is not necessary as the termination date supplied on the new deduction record can be directly used as a deduction stop date.
Stop Date -1 Example:
Original deduction date: 8/1/2018
Original subscriber premium amount: $101.58New deduction date: 2/1/2019
New subscriber premium amount: $226.06Before applying the new deduction amount and effective date, payroll vendor will use the 2/1/2019 change_effective_date - 1 day = 1/31/2019 and process a deduction stop date. The payroll vendor can then process the new deduction with a 2/1/2019 start date. This logic is not built into PlanSource and should exist on the payroll vendors system if needed.
Updated about 5 years ago