Search Results payroll_actions

Overview

The APPS.PAY_US_TAX_BALS_ADJ_PKG package body (source file pyustxba.pkb) provides the core tax balance adjustment logic for the United States localization of Oracle Payroll. Its business purpose is to create and apply adjustments to payroll tax balances when a user or process needs to correct or retroactively modify taxable wage and tax withholding amounts. The package was originally created in October 1995 and has been maintained through numerous versions, reflecting its role as a long-standing, foundational component of US payroll processing.

The balances affected by the package depend on which amounts are supplied. When a gross amount is not provided but a tax amount is, only withheld balances are adjusted. When a gross amount is provided without a tax amount, only subject (taxable wage) balances are adjusted. When both are supplied, both subject and withheld balances are adjusted. Subject balances are further refined based on the taxability rules applicable to the employee's work state, ensuring that wage adjustments respect jurisdictional tax rules.

Key Procedures and Functions

The package exposes a single documented entry point: CREATE_TAX_BALANCE_ADJUSTMENT. This procedure performs the balance adjustment work described above, accepting the identifying context needed to locate the payroll action and earnings being adjusted, and applying the appropriate adjustment to the relevant tax balances. It encapsulates the logic for determining which balances apply based on whether a gross amount and/or tax amount have been entered, and it resolves the correct tax jurisdiction for withholding and subject taxes.

Historically the package also incorporated internal routines referenced in its version history, such as derive_jd_geocode and supplemental tax input population for FIT and SIT when earnings are supplemental. These support the primary adjustment procedure rather than forming separate documented APIs. Only CREATE_TAX_BALANCE_ADJUSTMENT is classified in the ETRM metadata; the package classification is OTHER. No other packages reference this package, indicating it is an entry-point consumer rather than a shared utility.

Tables Accessed

The package reads and writes a broad set of US payroll and tax configuration tables through APPS synonyms. Element and entry definitions are resolved via PAY_ELEMENT_TYPES_F, PAY_ELEMENT_ENTRIES_F, PAY_ELEMENT_CLASSIFICATIONS, and PAY_INPUT_VALUES_F. The payroll action context is sourced from PAY_PAYROLL_ACTIONS, while actual results are read from PAY_RUN_RESULTS. Taxability behavior is driven by PAY_TAXABILITY_RULES. Jurisdictional tax configuration is drawn from PAY_US_FEDERAL_TAX_INFO_F, PAY_US_STATE_TAX_INFO_F, PAY_US_CITY_TAX_INFO_F, PAY_US_COUNTY_TAX_INFO_F, PAY_US_STATES, PAY_US_COUNTIES, and PAY_US_EMP_FED_TAX_RULES_F. Consolidation context is obtained from PAY_CONSOLIDATION_SETS.

Usage Notes

In Oracle EBS 12.1.1 and 12.2.2, PAY_US_TAX_BALS_ADJ_PKG is typically invoked from the Adjust Balance or Balance Adjustment functionality within US Payroll, and may also be called from the payroll run processing flow when retroactive tax adjustments are required. Because it is an OTHER-classified package with no referencing packages, custom code should treat CREATE_TAX_BALANCE_ADJUSTMENT as the sole supported entry point and avoid reliance on internal routines. Implementers extending or calling this package should ensure the employee's work location and state are valid and that the state is subject to the relevant taxes (SIT, SUI, SDI) before invocation, as location and taxability validation is integral to its processing.