> ## Documentation Index > Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt > Use this file to discover all available pages before exploring further. # Configuring Benefits > Managing payroll contributions for employee and employer benefits Benefits represent payroll contributions tied to employer or employee plans. These contributions may be monetary or calculated based on earnings, and may be shared between the employer and the employee. Benefits are configured using two distinct entities: * **Employer Benefits**: Contributions paid by the employer towards employee benefit plans. * **Employee Benefits**: Contributions deducted from the employees earnings to contribute to their benefits. Both types can generate **line items** during payroll, which represent actual contributions applied per pay period. *** ## Employer Contributions ### Employer Benefits Employer Benefits represent the configuration of recurring contributions made by the employer towards benefit plans, such as health insurance or retirement contributions. * Employer Benefits are contributions made by the employer towards employee benefit plans. * They can be fixed amounts or calculated based on employee earnings. * During the effective dates, these contributions are automatically applied to the payroll as an Employer Benefit Line Item. * Employer Benefits can be inherited from a Business Preset, allowing for consistent benefit configurations across multiple work assignments. | Field | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `work_assignment_id` | Required. The work assignment this benefit applies to. Must belong to a work assignment associated with an entity of type Employee. | | `business_preset_id` | Optional Business Preset to inherit from. | | `employer_benefit_type` | The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`). Required unless inherited from a Business Preset. | | `employee_benefit_id` | Optional reference to an employee\_benefit used solely for display. | | `title` | Label for identifying the benefit. | | `effective_from` | Start date of the Benefit. | | `effective_to` | The end date for this plan (optional) | | `frequency` | How often the benefit applies (e.g. `once`, `per_payroll`, `per_month`) | | `income_basis` | Income basis used for percentage-based benefits (`regular_earnings`, `total_income`) | | `income_includes` | Narrows which earnings count towards percentage-based benefits. Each entry sets a `type` (`earning`, `allowance`, or `reimbursement`) and a `subtype`. | | `amount` | Fixed contribution amount (optional) | | `percent` | Percent of eligible earnings (optional) | | `max_annual_contribution` | Optional annual contribution cap | | `max_annual_contribution_basis` | What the annual cap applies to. `this_benefit` caps this benefit on its own. `all_line_items_of_type` shares one cap across every benefit of the same type (for example, two separate RRSP plans count toward a single yearly limit). | | `coverage_multiplier` | Coverage multiplier used for life insurance plans. | | `remittance_account_id` | The remittance account these contributions are paid out to. | | `expense_accounting_code_id` | Accounting code that routes the expense side of this benefit. | | `liability_accounting_code_id` | Accounting code that routes the liability side of this benefit. | For the complete list of accepted fields, see the [Create an Employer Benefit](/api-reference/employer-benefits/create-an-employer-benefit) API reference. > 🔍 Note: employee\_benefit\_id is used only for UI grouping. No values are inherited, and changes to one do not affect the other. ## Employee Contributions Employee Benefits represent the configuration of recurring contributions deducted from the employees earnings towards benefit plans, such as health insurance or retirement contributions. * They can be fixed amounts or calculated based on employee earnings. * During the effective dates, these contributions are automatically applied to the payroll as an Employee Benefit Line Item. * Employee Benefits can be inherited from a Business Preset, allowing for consistent benefit configurations across multiple work assignments. ### Key Fields | Field | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `work_assignment_id` | Required. The work assignment this benefit applies to. Must belong to a work assignment associated with an entity of type Employee. | | `business_preset_id` | Optional Business Preset to inherit from. | | `employee_benefit_type` | The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`). Required unless inherited from a Business Preset. | | `employer_benefit_id` | Optional reference to an employer\_benefit used solely for display. | | `title` | Label for identifying the benefit. | | `effective_from` | Start date of the benefit. | | `effective_to` | The end date for this plan (optional) | | `frequency` | How often the benefit applies (e.g. `once`, `per_payroll`, `per_month`) | | `income_basis` | Income basis used for percentage-based benefits (`regular_earnings`, `total_income`) | | `income_includes` | Narrows which earnings count towards percentage-based benefits. Each entry sets a `type` (`earning`, `allowance`, or `reimbursement`) and a `subtype`. | | `amount` | Fixed contribution amount (optional) | | `percent` | Percent of eligible earnings (optional) | | `max_annual_contribution` | Optional annual contribution cap | | `max_annual_contribution_basis` | What the annual cap applies to. `this_benefit` caps this benefit on its own. `all_line_items_of_type` shares one cap across every benefit of the same type (for example, two separate RRSP plans count toward a single yearly limit). | | `coverage_multiplier` | Coverage multiplier used for life insurance plans. | | `remittance_account_id` | The remittance account these contributions are paid out to. | | `expense_accounting_code_id` | Accounting code that routes the expense side of this benefit. | | `liability_accounting_code_id` | Accounting code that routes the liability side of this benefit. | For the complete list of accepted fields, see the [Create an Employee Benefit](/api-reference/employee-benefits/create-an-employee-benefit) API reference. > 🔍 Note: employer\_benefit\_id is used only for UI grouping. No values are inherited, and changes to one do not affect the other. ## Validations * Only one of `amount` or `percent` may be set per benefit. Attempts to set both will result in a validation error. * A benefit must include a `*_benefit_type` unless inherited from a Business Preset. *** ## Contribution Limits Each benefit can have a `max_annual_contribution` defined to set an annual limit, which is enforced during payroll processing. * `max_annual_contribution_basis` sets what the annual cap applies to. `this_benefit` (the default) caps this benefit on its own. `all_line_items_of_type` shares one cap across every benefit of the same type, so two separate RRSP plans count toward a single yearly limit. * The limit resets at the start of each calendar year. * Only paid line items count towards the limit. * Historical Year-To-Date (YTD) contributions are not considered when calculating contributions towards the limit. ### Employer Benefit Line Items Employer Benefit Line Items represent the actual contributions made by the employer towards employee benefit plans during payroll processing. These line items are generated based on the configured Employer Benefits, or can be created directly for one-time contributions. | Field | Description | | ------------------------- | ------------------------------------------------------------------------------------------- | | `business_preset_id` | Optional Business Preset to inherit from. | | `employer_benefit_type` | The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`) | | `recurrence` | The employer benefit which generated this line item (read-only) | | `title` | Label for identifying the benefit line item. | | `amount` | Actual dollar value for this line item (read-only) | | `custom_amount` | User settable value for the line item amount, always takes precedence over `managed_amount` | | `managed_amount` | The calculated value for this line item. | | `max_annual_contribution` | Optional annual contribution cap | | `coverage_multiplier` | Coverage multiplier used for life insurance plans. | *** ### Employee Benefit Line Items Employee Benefit Line Items represent the actual contributions made by the employee towards benefit plans during payroll processing. These line items are generated based on the configured Employee Benefits, or can be created directly for one-time contributions. | Field | Description | | ------------------------- | ------------------------------------------------------------------------------------------- | | `business_preset_id` | Optional Business Preset to inherit from. | | `employee_benefit_type` | The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`) | | `recurrence` | The employee benefit which generated this line item (read-only) | | `title` | Label for identifying the benefit line item. | | `amount` | Actual dollar value for this line item (read-only) | | `custom_amount` | User settable value for the line item amount, always takes precedence over `managed_amount` | | `managed_amount` | The calculated value for this line item. | | `max_annual_contribution` | Optional annual contribution cap | | `coverage_multiplier` | Coverage multiplier used for life insurance plans. | *** ### Benefit Types Employee and employer benefits each have their own set of supported benefit types, which may overlap. You can retrieve the lists using the following endpoints: * `GET /employee_benefit_types`: Returns all employee benefit types * `GET /employer_benefit_types`: Returns all employer benefit types Each benefit type object includes: * `type`: the unique identifier used in the API, e.g. `critical_illness`, `pension_dcpp`. * `label`: a human-readable name for display purposes, e.g "Critical Illness", "Defined Contribution Pension Plan (DCPP)". *** ## Example Scenarios ### A. One-Time Dental Contribution Creates a one-time \$125 employee-only dental benefit: ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/employee_benefits \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "work_assignment_id": "...", "employee_benefit_type": "dental", "frequency": "once", "amount": 125, "effective_from": "2025-04-01", "title": "Employee Dental Plan Contribution" }' ``` *** ### Recurring Employee RRSP contribution A recurring RRSP contribution of \$150 each payroll with an annual maximum of \$600, starting from January 1, 2025: ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/employee_benefits \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "work_assignment_id": "...", "employee_benefit_type": "pension_rrsp", "frequency": "per_payroll", "amount": 150, "max_annual_contribution": 600, "effective_from": "2025-01-01" }' ``` *** ### Shared Health Plan A recurring Health contribution: * Employer contributes \$50 per payroll. * Employee contributes \$25 per payroll. * The two benefits are linked, allowing the two benefits to be displayed together in payroll. ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/employer_benefits \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "work_assignment_id": "...", "employer_benefit_type": "health", "frequency": "per_payroll", "amount": 50, "effective_from": "2025-01-01" }' ``` ```bash theme={null} curl --request POST \ --url https://sandbox.nmbr.co/services/payroll/employee_benefits \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "work_assignment_id": "...", "employer_benefit_id": "", "employee_benefit_type": "health", "frequency": "per_payroll", "amount": 25, "effective_from": "2025-01-01" }' ```