Along with standard payroll withholdings such as income tax and social security, some employees may need additional deductions withheld from their checks, such as 401K contributions or garnishments. ## In this guide - What makes up a Deduction Template Definitions. - How to define deduction rules with a Deduction Template. - How to add a Deduction to an Employee Check. - How to create recurring deductions from the Company Dashboard. * * * ## API Accounting for deductions with Zeal's API is a 2-step process: 1. Create a Deduction Template 2. Create a Deduction (scoped to a single Employee Check) ### Understanding Deduction Template Definitions Before creating a Deduction Template, we should first get the Deduction Template Definition Object for the type of deduction (401K, HSA, etc.) we want to address. This object is presented as a [JSON schema](https://json-schema.org/) and defines the instructions, or possible options available, when creating a Deduction Template. This JSON schema can be a little complicated, so let's break it down into pieces. ```json // Full HSA Deduction Template Definition Object { "type": "object", "required": [ "employee_contribution", "additional_fields" ], "properties": { "required_template_fields": { "const": [ "employee_contribution" ] }, "custom_name": { "type": "string" }, "deduction_type": { "const": "hsa" }, "employee_contribution": { "type": "object", "properties": { "contribution_type": { "enum": [ "dollars" ] }, "value": { "type": "number" }, "override_type": { "enum": [ "overridable", "needs_input", "final" ] }, "required_template_fields": { "const": [ "value" ] } }, "allOf": [ { "if": { "properties": { "override_type": { "const": "final" } }, "required": [ "override_type" ] }, "then": { "required": [ "value" ] } }, { "if": { "properties": { "override_type": { "const": "overridable" } }, "required": [ "override_type" ] }, "then": { "required": [ "value" ] } } ], "required": [ "override_type", "contribution_type" ] }, "employer_contribution": { "type": "object", "properties": { "contribution_type": { "enum": [ "dollars" ] }, "value": { "type": "number" }, "override_type": { "enum": [ "overridable", "needs_input", "final" ] }, "required_template_fields": { "const": [ "value" ] } }, "allOf": [ { "if": { "properties": { "override_type": { "const": "final" } }, "required": [ "override_type" ] }, "then": { "required": [ "value" ] } }, { "if": { "properties": { "override_type": { "const": "overridable" } }, "required": [ "override_type" ] }, "then": { "required": [ "value" ] } } ], "required": [ "override_type", "contribution_type" ] }, "additional_fields": { "type": "object", "properties": { "hsa_type": { "enum": [ "family", "individual" ] } }, "required": [ "hsa_type" ] } } } ``` #### Properties The first thing to note is the `properties` field. ```json // Snippet Showing Properties // inner details of objects have been omitted for brevity { "properties": { "required_template_fields": { }, "custom_name": { }, "deduction_type": { }, "employee_contribution": { "properties": { "contribution_type": { }, "value": { }, "override_type": { }, "required_template_fields": { } }, "employer_contribution": { "properties": { "contribution_type": { }, "value": { }, "override_type": { }, "required_template_fields": { } }, }, "additional_fields": { "properties": { "hsa_type": { } }, } } } } ``` With the exception of `required_template_fields`, all keys of a `properties` field directly translate to fields that may be included in the body of your POST request to the [Create a Deduction Template endpoint](https://docs.zeal.com/reference/create-deduction-template). ```json // Example Request Body to Create a HSA Template { "companyID": "{{companyID}}", "deduction_type": "hsa", "custom_name": "Test HSA", "employee_contribution": { "contribution_type": "dollars", "override_type": "needs_input" }, "employer_contribution": { "contribution_type": "dollars", "value": 0, "override_type": "overridable" }, "additional_fields": { "hsa_type": "individual" } } ``` #### Property Values The Deduction Template Definition also tells us the values we can assign to the fields of each property. There are a few different types of values these fields might hold, so let's go through them. - `const` - field is restricted to the value listed. - `enum` - field is restricted to one of the values listed. - `type` - field is restricted to the _type_ listed (ex. "number" -> `5`). ```json // Snippet Showing Property Values { "properties": { "deduction_type": { "const": "hsa" }, "employee_contribution": { "type": "object", "properties": { "contribution_type": { "enum": [ "dollars" ] }, "value": { "type": "number" }, "override_type": { "enum": [ "overridable", "needs_input", "final" ] } } } } } ``` ### Required Fields In the example request body above, we included all of the property options that were listed in the HSA template definition. However, not all properties are required. The `required` fields tell us what properties must be included in our request. ```json // Snippet Showing Required Field { "required": [ "employee_contribution", "additional_fields" ], } ``` With this in mind, another valid request body to create an HSA template could be as follows since `employer_contribution` is not a required field. ```json // Example Request Body to Create a HSA Template { "companyID": "{{companyID}}", "deduction_type": "hsa", "custom_name": "Test HSA", "employee_contribution": { "contribution_type": "dollars", "override_type": "needs_input" }, "additional_fields": { "hsa_type": "individual" } } ``` #### Conditionally Required Fields One part of the schema that may not be immediately understood is the `allOf` fields. ```json // Snippet Showing allOf field { "properties": { "employee_contribution": { "allOf": [ { "if": { "properties": { "override_type": { "const": "final" } }, "required": [ "override_type" ] }, "then": { "required": [ "value" ] } }, { "if": { "properties": { "override_type": { "const": "overridable" } }, "required": [ "override_type" ] }, "then": { "required": [ "value" ] } } ] } } } ``` These fields control the conditions under which properties may be required depending on the value of another field. #### Required Template Fields With everything we've learned so far, we're ready to create Deduction Templates. But you may be thinking, "Hold on. What about this `required_template_fields`?" Great question! `required_template_fields` aren't included when creating a Deduction Template. Rather, these fields indicate what fields will be required in the subsequent step to create a Deduction using the template. For example, our HSA Template Definitions state these `required_template_fields`: ```json // Snippet Showing Required Template Fields { "properties": { "required_template_fields": { "const": [ "employee_contribution" ] }, "employee_contribution": { "required_template_fields": { "const": [ "value" ] } }, } } } ``` This means that when we create a Deduction using this Deduction Template, we'll need to include the `employee_contribution` object with the field `value` in our `deduction` object. ```json // Example Request Body to Create a HSA Deduction { "companyID": "{{companyID}}", "deductionTemplateID": "{{deductionTemplateID}}", "employeeCheckID": "{{employeeCheckID}}", "deduction": { "employee_contribution": { "value": 50 } } } ``` Now, we can easily complete the 2-step flow for creating Deduction Templates and Deduction Products. ### Create a Deduction Template A Deduction Template is an object that defines the schema for a Deduction. Deduction Templates may be reused across a company for many employees or just for a single employee. For example: - An employer might create a 401K Deduction Template that defines a fixed _employer contribution_ but allows the _employee contribution_ to be adjusted with each deduction created. This might be reused across multiple employees. - An employee has a particular case where many garnishments or miscellaneous need to be withheld from their paycheck. The Deduction Templates that are defined to accommodate this use case might only be used to create deductions for this particular employee. It’s important to understand the scope of a Deduction Template before creating it. Now we'll walk through creating a Deduction Template. 1. Call [Get Deduction Template Definitions](https://docs.zeal.com/reference/get-deduction-template-definitions) with the type of deduction you're targeting as a query parameter. We'll choose `401k` for this example. 2. Use the JSON Schema returned as instructions to build your request to create a deduction template. 3. Call [Create Deduction Template](https://docs.zeal.com/reference/create-deduction-template). ### Create a Deduction A Deduction defines how much should be withheld from an employee's pay and is scoped to a single Employee Check. Below are the steps to create a Deduction: 1. [Get Employee Checks by Employee](https://docs.zeal.com/reference/retrieve-employee-checks-by-employee) you would like to apply the Deduction to. 2. [Get a list of Deduction Templates](https://docs.zeal.com/reference/get-deduction-template) and grab the `deductionTemplateID` for the desired template. 3. [Create the Deduction](https://docs.zeal.com/reference/create-deduction). With your deduction in the system, Zeal will process the Deduction when the Employee Check is prepared.