Code Builders

This guide covers the payload builders for creating payroll-related "Code" entities in Acumatica, such as Deduction/Benefit codes and Earning Type codes. These builders are used with the `CodesService`.

Importing the Builders

The builders for payroll codes are located in the `easy_acumatica.models.code_builder` module.


from easy_acumatica.models.code_builder import (
    DeductionBenefitCodeBuilder,
    EarningTypeCodeBuilder,
    PayrollWCCCodeBuilder,
)

Builder Classes

DeductionBenefitCodeBuilder

This builder constructs the payload for creating a new Deduction or Benefit code. It provides methods to set all the necessary fields, including nested objects for GL accounts and employee deduction settings.


# Build the payload for a new 401k deduction code
deduction_payload = (
    DeductionBenefitCodeBuilder()
    .code_id("401K")
    .description("Employee 401k Contribution")
    .contribution_type("DED")  # 'DED' for Deduction, 'BEN' for Benefit
    .active(True)
    .employee_deduction(calculation_method="GRS", percent=5.0)
    .gl_accounts(deduction_liability_account="210100")
)

# Use the builder with the CodesService
# new_code = client.codes.create_deduction_benefit_code("24.200.001", builder=deduction_payload)

EarningTypeCodeBuilder

This builder constructs the payload for a new Earning Type code, which defines different types of employee compensation (e.g., regular wage, overtime, bonus).


# Build the payload for an Overtime earning type
earning_payload = (
    EarningTypeCodeBuilder()
    .code_id("OT")
    .description("Overtime Hourly")
    .category("Wage")
    .accrue_time_off(True)
    .active(True)
)

# Use the builder with the CodesService
# new_earning_type = client.codes.create_earning_type_code("24.200.001", builder=earning_payload)

PayrollWCCCodeBuilder

This builder is used to define Workers' Compensation Class Codes. Its structure is slightly different, as it involves setting a country and then adding one or more WCC codes to a list.


# Build the payload for US-based WCC codes
wcc_payload = (
    PayrollWCCCodeBuilder()
    .country("US")
    .add_wcc_code(wcc_code="8810", description="Clerical Office Employees")
    .add_wcc_code(wcc_code="7219", description="Trucking and Hauling")
)

# Use the builder with the CodesService
# new_wcc_codes = client.codes.create_payroll_wcc_code("24.200.001", builder=wcc_payload)