Codes Service

The `CodesService` 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.

Ensure the Payroll and US Payroll features are enabled in your Acumatica instance (CS100000) to use this service.

Importing Helpers

To create the different types of codes, you will need to import their corresponding builder classes from `easy_acumatica.models.code_builder`.


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

Service Methods

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.


# 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)
    .employee_deduction(calculation_method="GRS", percent=5.0)
    .gl_accounts(deduction_liability_account="210100")
)

# 2. Call the service method to create the code
new_code = client.codes.create_deduction_benefit_code(
    "24.200.001",
    builder=deduction_payload
)

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.


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

# 2. Call the service method
new_earning_type = client.codes.create_earning_type_code(
    "24.200.001",
    builder=earning_payload
)

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.


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

# 2. Call the service method
new_wcc_codes = client.codes.create_payroll_wcc_code(
    "24.200.001",
    builder=wcc_payload
)