This guide covers the CodesService, which is used to create various payroll-related "Code" entities in Acumatica. This service works in tandem with the Code Builders to construct and send the necessary payloads to the API.

1. Accessing the Service

The CodesService is accessed through your main AcumaticaClient instance.

Assuming 'client' is an initialized AcumaticaClient

codes_service = client.codes

2. Creating a Deduction or Benefit Code

create_deduction_benefit_code(api_version, builder)

This method creates a new Deduction or Benefit code, which is used to manage employee payroll deductions (like health insurance) or company contributions (like a 401k match).

You must provide a DeductionBenefitCodeBuilder object containing all the necessary details.

Example:

from easy_acumatica.models.code_builder import DeductionBenefitCodeBuilder

1. 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)  
    .associated_with("Employee Settings")  
    .employee_deduction(  
        calculation_method="GRS", # Percentage of Gross Pay  
        percent=5.0,  
        applicable_earnings="TOT"  
    )  
    .gl_accounts(  
        deduction_liability_account="210100",  
        deduction_liability_sub="000-002"  
    )  
)

# 2. Call the service method to create the code  
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. Creating an Earning Type Code

create_earning_type_code(api_version, builder)

This method creates a new Earning Type code, which defines different types of compensation an employee can receive, such as regular wages, overtime, bonuses, or commissions.

Example:

from easy_acumatica.models.code_builder import EarningTypeCodeBuilder

# 1. Build the payload for a 'Bonus' earning type  
earning_payload = (  
    EarningTypeCodeBuilder()  
    .code_id("BONUS")  
    .description("Discretionary Bonus")  
    .category("Wage")  
    .accrue_time_off(False) # This earning type does not accrue time off  
    .active(True)  
)

# 2. Call the service method  
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. Creating a Payroll WCC Code

create_payroll_wcc_code(api_version, builder)

This method is used to define Workers' Compensation Class (WCC) codes for a specific country. The builder for this method is structured to first set the country, and then add one or more WCC codes to it.

Example:

from easy_acumatica.models.code_builder import PayrollWCCCodeBuilder

# 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)  
    .add_wcc_code(wcc_code="5183", description="Plumbing and Fixture Installation", active=False)  
)

# 2. Call the service method  
try:  
    new_wcc_codes = client.codes.create_payroll_wcc_code(  
        "24.200.001",  
        builder=wcc_payload  
    )  
    print("Successfully created WCC codes for country: US")  
except Exception as e:  
    print(f"Failed to create WCC codes: {e}")