Guidelines for Maintaining Tax Withholding Cards for the United States

Tax Withholding

If you’re updating tax information for an existing Tax Withholding calculation card always include the Tax Withholding record to group other related data supplied in the file. The effective start date you specify for the Tax Withholding record must be the original effective start date of the card.

When supplying the Tax Withholding record use the TaxWithholding file discriminator. For autogenerated cards you’re unlikely to know the source key that identifies the record, so use these attributes to identify the card.

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
EffectiveStartDate	The start date of the card, typically the employee’s hire date.

For example:

METADATA|TaxWithholding|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|SourceRef001=AssignmentNumber
MERGE|TaxWithholding|US LDG|E12833|1|2017/01/01|E12833

Federal Taxes

If correcting the existing Federal Taxes card component, the effective start date must be the original start date of the Federal Taxes. You can load date-effective history, or update Federal Taxes, for example when a new override value needs to be populated. When supplying the Federal Taxes record use the FederalTaxes file discriminator. For autogenerated cards you’re unlikely to know the source key that identifies the record, so use these attributes to identify the card.

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
EffectiveStartDate	The start date of the card, typically the employee’s hire date.

This example updates an existing Federal Taxes card component which starts on 1st Jan 2017 with the Tax Withholding card. The update to the Federal Taxes card component is made on 1st Jan 2023 to populate field values.

METADATA|TaxWithholding|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate
MERGE|TaxWithholding|US LDG|E12833|1|2017/01/01

METADATA|FederalTaxes|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|ExemptfromMedicare|RegularAmount
MERGE|FederalTaxes|US LDG|E12833|1|2023/03/01|Y|550

State Taxes

There is a separate component in the Tax Withholding object hierarchy for each US state. They include only the attributes specific to that state. When supplying State Taxes records use the file discriminator specific to the state you are providing data for, such as StateTaxesOH for Ohio. Use the View Business Objects task to identify the file discriminator and available attributes for each state.

Note: State Withholding Overrides are in separate regions for Residential and Nonresidential. We use the same field names in each region. When loading these values, the residential fields will not have a prefix. The Nonresidential fields will have a prefix and will be loaded as: NonresidentialWithholdingOverrides_<field name>.

For autogenerated cards you’re unlikely to know the source key that identifies the record, so use these attributes to identify the card.

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
EffectiveStartDate	The start date of the state taxes.

This example uses user keys to identify the Tax Withholding card and State Taxes. It creates State Taxes for California from 1st Jan 2023, setting the following fields:

Field	Value
Filing Status	Single
Number of Regular Withholding Allowances	1
Total Number of Allowances	1

METADATA|TaxWithholding|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|SourceRef001=AssignmentNumber
MERGE|TaxWithholding|US LDG|E12833|1|2017/01/01|E12833

METADATA|StateTaxesCA|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|FilingStatus|NumberofRegularWithholdingAllowances|TotalNumberofAllowances
MERGE|StateTaxesCA|US  LDG|E12833|1|2023/01/01|Single|1|1

Pennsylvania PSD

When supplying Pennsylvania PSD use the PennsylvaniaPSD file discriminator. The following attributes are always required. Use the View Business Objects task to find other optional attributes for Pennsylvania PSD.

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
TaxReportingUnit	The tax reporting unit tied to the employee residency certificate.
EffectiveStartDate	The start date of the county taxes or update to the county taxes.

This example creates Pennsylvania PSD on the 1st Jan 2017 referring to the existing Tax Withholding card by user keys. The following field are set:

Field	Value
Tax Reporting Unit	US TRU
Resident PSD Code	10404
Resident School District	Gettysburg ASD
Work PSD Code	10404
Work School District	Gettysburg ASD

METADATA|TaxWithholding|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|SourceRef001=AssignmentNumber
MERGE|TaxWithholding|US LDG|E91747|1|2017/01/01|E91747

METADATA|PennsylvaniaPSD|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|TaxReportingUnit|ResidentPSDCode|ResidentSchoolDistrict|WorkPSDCode|WorkSchoolDistrict
MERGE|PennsylvaniaPSD|US LDG|E91747|1|2017/01/01|US TRU|10404|Gettysburg ASD|10404|Gettysburg ASD

County Taxes

When supplying County Taxes use the CountyTaxes file discriminator. The following attributes are always required. Use the View Business Objects task to find other optional attributes for County Taxes.

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
State	The two-letter abbreviation for the state, such as OH for Ohio.
County	The name of the county. Alternatively, supply the geocode for the county.
EffectiveStartDate	The start date of the county taxes or update to the county taxes.

This example identifies the existing Tax Withholding card and new County Taxes card component by user keys. It creates County Taxes from the 1st January 2023 setting the following fields:

Field	Value
State	KY
County	Grant
Resident County Tax Regular Amount	25

METADATA|TaxWithholding|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|SourceRef001=AssignmentNumber
MERGE|TaxWithholding|US LDG|E12833|1|2017/01/01|E12833

METADATA|CountyTaxes|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|State|County|ResidentCountyTaxRegularAmount
MERGE|CountyTaxes|US LDG|E12833|1|2023/01/01|KY|Grant|25

City Taxes

When supplying City Taxes use the CityTaxes file discriminator. The following attributes are always required. Use the View Business Objects task to find other optional attributes for City Taxes.

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
State	The two-letter abbreviation for the state, such as OH for Ohio.
County	The name of the county. Alternatively, supply the geocode for the county.
City	The name of the city. Alternatively, supply he geocode for the city.
EffectiveStartDate	The start date of the county taxes or update to the county taxes.

This example identifies the existing Tax Withholding card and new City Taxes card component by user keys. It creates City Taxes on the 1st Jan 2023 with the following values:

Field	Value
State	PA
County	Philadelphia
City	Philadelphia
Nonresident City Tax Regular Amount	200
Nonresident City Tax Supplemental Amount	100

METADATA|TaxWithholding|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|SourceRef001=AssignmentNumber
MERGE|TaxWithholding|US LDG|E12833|1|2017/01/01|E12833

METADATA|CityTaxes|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|State|County|City|NonresidentCityTaxRegularAmount|NonresidentCityTaxSupplementalAmount
MERGE|CityTaxes|US LDG|E12833|1|2023/01/01|PA|Philadelphia|Philadelphia|200|100

US Taxation

When supplying US Taxation records use the USTaxation file discriminator. The following attributes are required or commonly used. Use the View Business Objects task to find other optional attributes for US Taxation.

Create or Update

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
EffectiveStartDate	The start date of the card, typically the employee’s hire date.
AssociationAssignmentNumber	The Tax Withholding card is identified by the employee’s primary assignment. If additional assignments are to be associated with the card supply the assignment number to this attribute.
TaxReportingUnit	The tax reporting unit associated to the US Taxation Component.

This example corrects the autogenerated US Taxation:

METADATA|TaxWithholding|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate
MERGE|TaxWithholding|US LDG|E12833|1|2017/01/01

METADATA|USTaxation|LegislativeDataGroupName|AssignmentNumber|CardSequence|EffectiveStartDate|TaxReportingUnit|StatutoryEmployee|PrimaryWorkAddress|StateforDisabilityCalculation|StateforUnemploymentCalculation|CumulativeTaxation
MERGE|USTaxation|US LDG|E12833|1|2017/01/01|US TRU|Y|DEFAULT|KY|KY|N

End Date Association:

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
EffectiveStartDate	The start date of the card, typically the employee’s hire date.
EffectiveEndDate	The end date of the record.
AssociationTaxReportingUnitName	Tax Reporting Unit associated to the US Taxation Component
ReplaceLastEffectiveEndDate	Y
TaxReportingUnit	The tax reporting unit associated to the US Taxation Component.

End Date Association Details:

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
EffectiveStartDate	The start date of the card, typically the employee’s hire date.
EffectiveEndDate	The end date of the association assignment.
AssociationAsignmentNumber	Assignment number being end dated.
ReplaceLastEffectiveEndDate	Y
TaxReportingUnit	The tax reporting unit associated to the US Taxation Component.

Delete Association:

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
EffectiveStartDate	The start date of the card, typically the employee’s hire date.
AssociationTaxReportingUnitName	The tax reporting unit on the US Taxation Component being deleted.
TaxReportingUnit	The tax reporting unit associated to the US Taxation Component.

Delete Association Details:

Attribute	Description
AssignmentNumber, or PayrollRelationshipNumber	Identify the employee the Tax Withholding card is for.
LegislativeDataGroupName	The name of the legislative data group for the calculation card.
CardSequence	The number that uniquely identifies the Tax Withholding card for the employee.
EffectiveStartDate	The start date of the card, typically the employee’s hire date.
AssociationAsignmentNumber	Assignment number being deleted.
TaxReportingUnit	The tax reporting unit associated to the US Taxation Component.