Code Builder - Nioron07/Easy-Acumatica GitHub Wiki

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.

1. 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,  
)

2. 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.

Example

Here is how to build a complete Deduction/Benefit code and send it to Acumatica.

# 1. Build the payload  
deduction_payload = (  
    DeductionBenefitCodeBuilder()  
    .code_id("HEALTH401")  
    .description("Employee Health 401k")  
    .contribution_type("DED")  # 'DED' for Deduction, 'BEN' for Benefit  
    .active(True)  
    .associated_with("Employee Settings")  
    .employee_deduction(  
        calculation_method="GRS", # Or "Fix" for fixed amount  
        percent=5.5,  
        applicable_earnings="TOT"  
    )  
    .gl_accounts(  
        deduction_liability_account="21000",  
        deduction_liability_sub="000-001"  
    )  
)

# 2. Use the builder with the CodesService  
try:  
    new_code = client.codes.create_deduction_benefit_code(  
        "24.200.001",  
        builder=deduction_payload  
    )  
    print(f"Successfully created code: {new_code['DeductionBenefitCodeID']['value']}")  
except Exception as e:  
    print(f"Failed to create code: {e}")

3. 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).

Example

# 1. 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)  
)

# 2. Use the builder with the CodesService  
try:  
    new_earning_type = client.codes.create_earning_type_code(  
        "24.200.001",  
        builder=earning_payload  
    )  
    print(f"Successfully created earning type: {new_earning_type['EarningTypeCodeID']['value']}")  
except Exception as e:  
    print(f"Failed to create earning type: {e}")

4. 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.

Example

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

# 2. Use the builder with the CodesService  
try:  
    new_wcc_codes = client.codes.create_payroll_wcc_code(  
        "24.200.001",  
        builder=wcc_payload  
    )  
    print("Successfully created WCC codes.")  
except Exception as e:  
    print(f"Failed to create WCC codes: {e}")