Requests that add modify or query workers comp codes

In QuickBooks, you need to create these workers compensation codes and the premiums (rates) that apply to them and then assign them to employees. You need to do this so QuickBooks can track the premiums you owe as you pay your employees.

Beginning with qbXML spec 7.0 and QuickBooks 2008, the Desktop SDK provides access to the workers comp code feature via the WorkersCompCodeAdd, WorkersCompCodeMod, and WorkersCompCodeQuery requests.

The following functionality related to workers comp is supported in the SDK

The following functionality is not supported in the SDK:

Note

Note

For both the QuickBooks UI and the SDK, you are able to access the QuickBooks workers’ comp codes feature only if the company file is subscribed to the Intuit payroll service, or, if the company file is a sample QuickBooks company.

If neither of these are the case, then you won’t be able to access the feature in the QuickBooks UI. In the SDK, you’ll get an error when you send workers’ comp code add, modify, or query requests.

How can I determine whether a company is subscribed to payroll?

PreferencesQuery and HostQuery do not indicate whether the company is subscribed to payroll.

However, you can determine this by simply issuing a WorkersCompCodeQuery and checking the response for the error status code of 3250, feature not available.

Here is a query you could use for this:

1
2
3
4
5
6
7
<?xml version="1.0"?>
<?qbxml version="7.0"?>
<QBXML>
<QBXMLMsgsRq onError="continueOnError">
<WorkersCompCodeQueryRq requestID="2" />
</QBXMLMsgsRq>
</QBXML>
Workers comp codes in the QuickBooks UI

In the QuickBooks UI (if the company is a sample company or subscribed to the Intuit payroll service), you you can view workers compensation codes by selecting List -> Workers Comp List to display the workers comp list:

../../../../_images/Image_438.jpg

In the list display form shown above, notice the code name, description, rate, and effective dates, which correspond to the SDK fields used in the WorkersCompCode Add/Mod/Query that we’ve called out in the figure. That form displays all of the names of the currently created codes, but only the dates and rates of codes that are currently in effect (see the entry in the figure for Salespersons). That is, if the code has a future effective date (or a past one) and no currently applicable effective date, the rate and date fields are empty in the list. That is why we show the <CurrentRate> and <CurrentEffectiveDate> tags in the figure.

Adding a workers comp code

To add a comp code via the UI, select List -> Workers Comp List->Workers Comp Code-> New to display the New Workers Compensation Code form.

../../../../_images/Image_443.jpg
Modifying a workers comp code

To edit a comp code via the UI, select List -> Workers Comp List->, then double-click the desired workers comp code to edit that code in the Edit Workers’ Compensation Code window:

../../../../_images/Image_449.jpg

The element names you use in WorkersCompCodeMod are shown in the figure next to the UI fields that they affect. Notice the two display-only text fields at the bottom of the form: there are no fields in the Modify request that correspond to these.

Workers comp codes with the Desktop SDK

The add and modify functionality covered above is also available with the Desktop SDK

Adding a workers comp code with the SDK

To add a workers comp code with the SDK, build and submit WorkersCompCodeAddRq message.

Several rates possible via Desktop SDK

In the QuickBooks UI, you can specify a comp code that has a single rate. However, in the SDK, you can create a comp code that has several rates, each of which has its own effective date.

Adding a comp code using QBFC

The following QBFC code (in VB) adds the workers’ comp code 8013. It has one rate that goes into effect on July 7, 2007.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
SessionManager.OpenConnection "", "IDN WorkersCompCode Add Sample"
SessionManager.BeginSession "", omDontCare

Dim WorkersCompCode_Set As IMsgSetRequest
Set WorkersCompCode_Set = SessionManager.CreateMsgSetRequest("US", 7, 0)

Dim WorkersCompCodeAdder As IWorkersCompCodeAdd
Set WorkersCompCodeAdder = WorkersCompCode_Set.AppendWorkersCompCodeAddRq
WorkersCompCodeAdder.Name.setValue "8013"
WorkersCompCodeAdder.Desc.setValue "driver"
WorkersCompCodeAdder.IsActive.setValue True
Dim RateEntree As IRateEntry
Set RateEntree = WorkersCompCodeAdder.RateEntryList.Append
RateEntree.EffectiveDate.setValue #7/7/2007 9:35:00 AM#
RateEntree.Rate.setValue 1#
Adding a comp code using qbXML

The following qbXML adds the workers’ comp code 8813. It has one rate that goes into effect on July 7, 2007, and another rate that supercedes that rate on January 7, 2008.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<?xml version="1.0"?>
<?qbxml version="7.0"?>
<QBXML>
    <QBXMLMsgsRq onError="continueOnError">
        <WorkersCompCodeAddRq requestID="2">
            <WorkersCompCodeAdd>
                <Name>8813</Name>
                <IsActive>true</IsActive>
                <Desc>tack driver</Desc>
                <RateEntry>
                    <Rate>1.00</Rate>
                    <EffectiveDate>2007-07-07</EffectiveDate>
                </RateEntry>
                <RateEntry>
                    <Rate>1.10</Rate>
                    <EffectiveDate>2008-01-07</EffectiveDate>
                </RateEntry>
            </WorkersCompCodeAdd>
        </WorkersCompCodeAddRq>
    </QBXMLMsgsRq>
</QBXML>
What can I do with the comp codes I create?

Once the workers comp codes are created, you use the workers’ comp code wizard within the QuickBooks UI to assign a code to an employee. You cannot assign codes to an employee from the SDK. Once a code is assigned, information about workers comp premiums paid for the employee are accessible through the various workers comp reports available through the QuickBooks UI.

Modifying workers comp codes with the SDK

Compared to the UI, using the SDK to modify comp codes provides you with a little more flexibility. That is, you can modify several rate entry aggregates, each with its own rate and corresponding effective date, whereas in the UI you can modify only one.

Modifying a comp code in qbXML

The following XML sample modifies a comp code with the name “8813” that has a single entry (rate and effective date).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?xml version="1.0"?>
<?qbxml version="7.0"?>
<QBXML>
    <QBXMLMsgsRq onError="continueOnError">
        <WorkersCompCodeModRq requestID="2">
            <WorkersCompCodeMod>
                <ListID>80000007-1197757964</ListID>
                <EditSequence>1197757964</EditSequence>
                <Name>8813</Name>
                <IsActive>true</IsActive>
                <Desc>operator</Desc>
                <RateEntry>
                    <Rate>1.00</Rate>
                    <EffectiveDate>2007-08-08</EffectiveDate>
                </RateEntry>
            </WorkersCompCodeMod>
        </WorkersCompCodeModRq>
    </QBXMLMsgsRq>
</QBXML>
Querying for workers comp codes with the SDK

To query for comp codes using the SDK, use the request WorkersCompCodeQuery. You can filter on the name of the code, the active status, effective date/date range, and modified date.

Notice that this query does not support iterators, as the number of codes is expected to be relatively small.

Querying for comp codes in qbXML

The following qbXML shows a query that checks for all comp codes (inactive as well as active) that have the number 5 in the comp code name, and that has an effective date between January 1, 2003 and December 28, 2008. Also, just to show another filter in the mix, we want only those that have been modified between the start of 2003 and the end of 2007.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<?xml version="1.0"?>
<?qbxml version="7.0"?>
<QBXML>
    <QBXMLMsgsRq onError="continueOnError">
        <WorkersCompCodeQueryRq requestID="2">
            <ActiveStatus>All</ActiveStatus>
            <FromModifiedDate>2003-01-01</FromModifiedDate>
            <ToModifiedDate>2007-12-28</ToModifiedDate>
            <NameFilter>
                <MatchCriterion>Contains</MatchCriterion>
                <Name>5</Name>
            </NameFilter>
            <FromEffectiveDate>2003-01-01</FromEffectiveDate>
            <ToEffectiveDate>2008-12-28</ToEffectiveDate>
        </WorkersCompCodeQueryRq>
    </QBXMLMsgsRq>
</QBXML>
Current effective date and current rate

When you add or modify a workers’ comp code through the SDK, you’ll notice that you can supply only the tags <Rate> and <EffectiveDate>. Where do the tags <CurrentRate> and <CurrentEffectiveDate> come from? Those tags are from the responses to the WorkersCompAdd/Mod/Query request. QuickBooks compares the supplied dates to the current date and figures out whether the supplied effective date is in the past, present, or future, and identifies the date as such in the Ret object.

Rate history: visible only through the Desktop SDK

QuickBooks maintains rate history. This rate history includes the current date and rate, one future date and rate and all past dates and rates. (If you already have a future effective date and rate, and then add a new future effective date and rate, the new entry replaces the currently existing one in the rate history.)

Although QuickBooks maintains the rate history, that history is not available in the QuickBooks UI. To see the rate history, you’ll need to check the response to a WorkersCompCode Add/Mod/Query request.

The rate history is shown in the RateHistory aggregates (in bold font) in the following response to a query request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?xml version="1.0" ?>
<QBXML>
    <QBXMLMsgsRs>
        <WorkersCompCodeModRs requestID="2" statusCode="0" statusSeverity="Info"
        statusMessage="Status OK">
            <WorkersCompCodeRet>
                <ListID>80000006-1197741184</ListID>
                <TimeCreated>2007-12-15T09:53:04-08:00</TimeCreated>
                <TimeModified>2007-12-15T15:39:35-08:00</TimeModified>
                <EditSequence>1197761975</EditSequence>
                <Name>66891</Name>
                <IsActive>true</IsActive>
                <Desc>ordinance defuser</Desc>
                <CurrentRate>78.00</CurrentRate>
                <CurrentEffectiveDate>2007-07-07</CurrentEffectiveDate>
                <NextRate>88.00</NextRate>
                <NextEffectiveDate>2008-07-07</NextEffectiveDate>
                <RateHistory>
                    <Rate>78.00</Rate>
                    <EffectiveDate>2007-07-07</EffectiveDate>
                </RateHistory>
                <RateHistory>
                    <Rate>88.00</Rate>
                    <EffectiveDate>2008-07-07</EffectiveDate>
                </RateHistory>
            </WorkersCompCodeRet>
        </WorkersCompCodeModRs>
    </QBXMLMsgsRs>
</QBXML>