Deduction Template Definition Object

Deduction Template Definition represents a JSON schema, which is essentially a way to represent instructions to create a Deduction Template in a JSON format.

With Zeal, using a Deduction Template Definition object, you first create a Deduction Template, and then subsequently create a Deduction using the Deduction Template, which also contains a JSON schema.

You can see below, the different types of Deduction Template Definition objects that Zeal returns

Types of Deductions

The following is a list of Deductions (both pre-tax and post-tax) that Zeal supports:

401k - (Pre Tax) A 401(k) plan is a tax-qualified, defined-contribution pension account that provides for pretax retirement savings.

hsa - (Pre Tax) A health savings account (HSA) is a tax-advantaged medical savings account enrolled in a high-deductible health plan. Funds accumulate and can be used to pay for qualified medical expenses without tax liabilities.

garnishment - (Pre Tax) A Wage Garnishment is a court-mandated withholding of an employee’s earnings from a paycheck for use toward debts. Common sources include: Child support, federal debt, state debt, student loans, and credit card debt. This serves as a post-tax deduction.

miscellaneous - (Post tax) Use this type for a generic post-tax deduction on the employee check.

section_125 - (Pre-tax) A benefit belonging to a Section 125 plan that allows employees to choose between different types of qualified benefits.

Override Types

  • final - Use this override_type when creating a Deduction Template, if you want to set the contribution field to only be set by the employer, and not let employees edit it. Example of this would be setting the employer contribution on a 401k

  • overridable - Use this override_type when creating a Deduction Template, if you want to set an initial value from the employer's side, but the employee can change it. Example of this would be setting the hsa_type to be individual at first, but allowing an employee to set it to family.

  • needs_input - Use this override_type when creating a Deduction Template, if you want the employee to set their contribution amount. If the field is left blank by the employee, it should be set to 0. Example of this would be an employee setting their preferred contribution amount for a 401k plan.

Contribution Types

  • dollars - Amount is accepted as cents e.g. 10034 to represent $100.34
  • percentage - Amount is to be accepted as a percentage, e.g. 10.21
{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "hsa"
        },
        "employee_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars",
                        "percentage"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "if": {
                "properties": {
                    "override_type": {
                        "const": "final"
                    }
                },
                "required": [
                    "override_type"
                ]
            },
            "then": {
                "required": [
                    "value"
                ]
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "employer_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars",
                        "percentage"
                    ]
                },
                "matching": {
                    "type": "boolean"
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "if": {
                "properties": {
                    "override_type": {
                        "const": "final"
                    }
                },
                "required": [
                    "override_type"
                ]
            },
            "then": {
                "required": [
                    "value"
                ]
            },
            "required": [
                "override_type",
                "contribution_type",
                "matching"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}
{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "401k"
        },
        "employee_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars",
                        "percentage"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "employer_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars",
                        "percentage"
                    ]
                },
                "percentage_source": {
                    "enum": [
                        "contribution",
                        "paycheck"
                    ]
                },
                "matching": {
                    "type": "boolean"
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type",
                "matching"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}
{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "section_125"
        },
        "employee_contribution": {
            "properties": {
                "contribution_type": {
                    "enum": [
                        "flat"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                }
            },
            "required_template_fields": {
                "const": [
                    "value"
                ]
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}
{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "miscellaneous"
        },
        "employee_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "employer_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars"
                    ]
                },
                "post_tax": {
                    "type": "boolean"
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}
{
    "success": true,
    "data": {
        "type": "object",
        "required": [
            "employee_contribution",
            "additional_fields"
        ],
        "properties": {
            "custom_name": {
                "type": "string"
            },
            "deduction_type": {
                "const": "garnishment"
            },
            "employee_contribution": {
                "type": "object",
                "properties": {
                    "contribution_type": {
                        "enum": [
                            "dollars"
                        ]
                    },
                    "override_type": {
                        "enum": [
                            "overridable",
                            "needs_input",
                            "final"
                        ]
                    },
                    "value": {
                        "type": "number"
                    }
                },
                "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",
                "required": [
                    "order_number",
                    "case_id",
                    "agency"
                ],
                "properties": {
                    "required_template_fields": {
                        "const": [
                            "agency",
                            "case_id"
                        ]
                    },
                    "order_number": {
                        "type": "object",
                        "properties": {
                            "override_type": {
                                "enum": [
                                    "overridable",
                                    "needs_input",
                                    "final"
                                ]
                            },
                            "value": {
                                "type": "string"
                            }
                        },
                        "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"
                        ]
                    },
                    "case_id": {
                        "type": "object",
                        "properties": {
                            "override_type": {
                                "enum": [
                                    "overridable",
                                    "needs_input",
                                    "final"
                                ]
                            },
                            "value": {
                                "type": "string"
                            }
                        },
                        "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"
                        ]
                    },
                    "agency": {
                        "type": "object",
                        "properties": {
                            "override_type": {
                                "enum": [
                                    "overridable",
                                    "needs_input",
                                    "final"
                                ]
                            },
                            "address": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "allOf": [
                            {
                                "if": {
                                    "properties": {
                                        "override_type": {
                                            "const": "final"
                                        }
                                    },
                                    "required": [
                                        "override_type"
                                    ]
                                },
                                "then": {
                                    "required": [
                                        "address",
                                        "name"
                                    ]
                                }
                            },
                            {
                                "if": {
                                    "properties": {
                                        "override_type": {
                                            "const": "overridable"
                                        }
                                    },
                                    "required": [
                                        "override_type"
                                    ]
                                },
                                "then": {
                                    "required": [
                                        "address",
                                        "name"
                                    ]
                                }
                            }
                        ],
                        "required": [
                            "override_type"
                        ]
                    }
                }
            }
        }
    }
}