SDK support for the QuickBooks vehicle mileage feature

In QuickBooks, vehicle mileage tracking is trip-based, with each trip and its mileage entered as a separate transaction in QuickBooks, with QuickBooks automatically calculating the resulting mileage costs based on user supplied rates. When you need to see the information accumulated from these transactions, you can run the Mileage by Vehicle or Mileage by Job reports. The following figure shows how this works in the Mileage by Vehicle report:

In addition to accumulating and generating data for reports, another way to use the vehicle mileage feature is to use it in conjunction with invoices to bill customers for mileage- related charges. To use the feature in this way you simply make the transaction billable and add a little more information to the vehicle mileage transaction, such as the customer to be charged and the item used to set the billable mileage rate. The following example shows how this is done in the QuickBooks UI.

Keep in mind that the tax mileage rate is completely unrelated to and unaffected by the billable mileage rate, and cannot be set via the SDK. For that reason, QuickBooks provides two separate mileage reports: Mileage by Vehicle, which reports only the tax-related vehicle mileage and mileage expense, and Mileage by Job, which tracks both non billable and billable mileage (along with the billable charges).

One key limitation of the SDK’s support of this feature is that you cannot automate the insertion of billable mileage charges directly into invoices via QB SDK requests. Only the QuickBooks interactive user can do that because it entails choosing charges from a list of outstanding customer charges at the time of invoice creation, and the company owner (the QuickBooks interactive user) must remain in control of this.

Another limitation, which we have already mentioned, is that the mileage rate used to calculate mileage expense for the tax agency (such as the IRS) can only be set in the QuickBooks UI, via the Mileage Rates button in the Mileage entry form. Only the billable mileage rate can be specified via the QB SDK, by setting the amount in the item (service item or other charge item) you use for mileage charges.

Finally, the Vehicle Mileage Mod operation is currently not supported, whereas you can modify a vehicle mileage transaction in the UI.

The best way to see how the mileage feature works is to look at the QuickBooks UI. The next figure shows the Vehicle Mileage entry form, which is where you create the mileage transactions in the UI.

We’ll describe most of the fields in the following paragraphs, at least, those fields that need some description beyond what’s obvious in the UI form.

Vehicle. You must always specify a vehicle. In the UI , a dropdown list contains all of the vehicles in the vehicle list. You can choose one or create a new vehicle by selecting New within the list. The SDK differs slightly, as you use the VehicleRef element to specify the vehicle, and the vehicle must already exist in the QuickBooks company.

Trip Start Date/End Date. This is an optional field. In the UI, the default is the current date, and this is always supplied if you don’t supply a different date. In the SDK, this corresponds to the elements TripStartDate and TripEndDate. If you omit either or both of these, the current date will be supplied for the omitted element(s).

Odometer Start/Odometer End/Total Miles. In the UI, you can specify values for all three of these fields, as long as the total miles matches the QuickBooks-calculated value for Odometer End minus Odometer Start. In the SDK, in the VehicleMileageAdd request, you can specify either the Odometer Start and End or you can specify Total Miles, but you cannot specify both, since doing so results in a parser error. The VehicleMileageAdd elements corresponding to these UI fields are as you would expect: OdometerStart, OdometerEnd, and TotalMiles.

Billable. One of the key choices you make when filling out this form, or doing the equivalent in the SDK, is whether a customer is to be charged for the mileage.

If a customer is to be charged, check the Billable checkbox in the upper right of the form. In the SDK, set the BillableStatus element in the VehicleMileageAdd request to Billable. Then specify the customer to be billed and the item used to set the charged mileage rate.

QuickBooks will save the tax related expense data, and will also save the mileage charge as an outstanding time or cost for that customer.

If you don’t intend to charge the customer, in the UI leave the checkbox unchecked. In the SDK, set the BillableStatus to NotBillable. You can omit customer and item, or you can optionally supply the customer and item, if for some reason you want to track this in the Mileage By Job detail report under that supplied customer. If you supply customer and item in a non billable transaction, the entry will be listed in the Mileage by Job detail report as Non Billable and no customer charge will be made.

Customer:Job. You must specify a customer if you check the Billable checkbox or do the equivalent in the VehicleMileageAdd request by setting BillableStatus to Billable.The UI control here is a dropdown list containing all of the customers in the customers list. You can create a new customer by selecting New within the list. In the VehicleMileageAdd request you use the CustomerRef element to specify the customer, and the customer must already exist in the QuickBooks company.

The billable charge resulting from this mileage transaction will be saved in QuickBooks as an outstanding Billable Time and Cost for that customer. The next time an invoice is created for that customer in the UI, the QuickBooks user will be prompted to add that outstanding charge to the invoice. Notice that no such prompt will occur for invoices created via the SDK, nor will you be able to insert any of these outstanding charges into the invoice via the SDK.

Item. You must specify an item if you check the Billable checkbox or do the equivalent in the SDK. The UI control here is the familiar dropdown list but it is a filtered list of only service items and other charge items. These are the only item types that can be used in vehicle mileage transactions. If you supply an item of a different type than service or other charge via the SDK, you’ll get a runtime error.

Mileage Rate. A UI-only feature. The Mileage Rate button is located in the top middle of the Vehicle Mileage entry form. You click on it to display the Mileage Rates form, which is where you specify the mileage rate for your current tax year. This rate is established by your income tax authority, for example, the IRS. This rate multiplied by the mileage from the mileage transactions yields the mileage expense reported by the Mileage By Vehicle reports.

Notice that you can change this rate from the UI whenever you want for that tax year, and the Mileage by Vehicle reports automatically reflect those changes. However, you cannot set or modify this rate via the SDK.

Mileage Reports. A UI-only feature. The mileage reports can be accessed via this button in the Vehicle Mileage entry form, or through the usual UI features that support reports: the Report Center or the Report pulldown menu.

The reports consist of two main reports:

• Summary and detail reports for Mileage by Vehicle, which lists the mileage and expenses calculated using the mileage rates set via the Mileage Rate button.
• Summary and detail reports for Mileage by Job, which lists the mileage and charges for each customer. The charges are derived from the mileage multiplied by the rate specified in the item used in the mileage transaction.

If you want to bill your customers for mileage, you need to create a service item or an other charge item that will show up on the invoice as the line item and also establish the mileage rate. The following figure shows a sample service item set up to bill the mileage at a rate of 0.70 per mile.

Keep in mind that the Rate field in service items, and the Amount field in other charge items are both used in Mileage transactions in exactly the same way. That is, they are rates, and they are multiplied against the mileage in a mileage transaction to yield the charges for the customer. They cannot be used to establish a flat fee amount.

Other than the Rate/Amount issue, there is nothing special to note here, except that when you create either a service item or an other charge item to bill customers against, the account you specify for that item is typically an income account. The tax code field refers to sales tax. If your company doesn’t use sales tax, then this doesn’t appear as a choice.

What Happens to Mileage Charges When I Create Invoices?

The behavior of invoices and mileage charges varies slightly depending on whether you add the invoice from the UI or via the SDK

In the UI, when you create an invoice for a customer who has any outstanding charges, such as mileage charges from Vehicle Mileage transactions, you are prompted to added them to the invoice, as shown in the following figure:

If you want to add these charges and click OK, a selection form, shown in the following figure, is displayed. The list of outstanding mileage charges for the customer is displayed when you select the Mileage tab.

You apply charges to the invoice by selecting them then clicking OK. The charges appear as line items in the invoice.

What happens when you create an invoice for a customer via the SDK by issuing the InvoiceAdd request? If that customer has outstanding mileage charges, how do you get those charges into the invoice? Is the outstanding charges prompt dialog displayed, as it is when you create an invoice via the UI?

The answer is that you cannot add these mileage charges at all if you are creating invoices via the SDK. No prompt is displayed to allow the user to add the charges to the invoice as the SDK creates them. The only way to add a customer’s outstanding mileage charges is for a user to create the invoice entirely from the UI.

You can use qbXML to add the transaction or you can use QBFC.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<?xml version="1.0"?>
<?qbxml version="6.0"?>
<QBXML>
    <QBXMLMsgsRq onError="continueOnError">
        <VehicleMileageAddRq requestID = "UUIDTYPE">
            <VehicleMileageAdd >
                <VehicleRef>
                    <FullName>Land Lugger</FullName>
                </VehicleRef>
                <CustomerRef>
                    <FullName>Jim Fuller</FullName>
                </CustomerRef>
                <ItemRef>
                    <FullName>Delivery Fee</FullName>
                </ItemRef>
                <OdometerStart>1500</OdometerStart>
                <OdometerEnd>1600</OdometerEnd>
                <BillableStatus>Billable</BillableStatus>
            </VehicleMileageAdd>
        </VehicleMileageAddRq>
    </QBXMLMsgsRq>

</QBXML>

The following VB sample shows how to build a VehicleMileageAdd request using QBFC. It is a one-shot sample that opens the connection with the currently open QuickBooks company, starts the session, builds a billable mileage request, sends it to QuickBooks.

The transaction properties are all set with hardcoded values, since the purpose of this snippet is only to show how to build the VehicleMileageAdd request.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

SessionManager As QBSessionManager
Set SessionManager = New QBSessionManager SessionManager.OpenConnection "",
"VehicleMileageAdd_Sample"
SessionManager.BeginSession "", omDontCare
Dim VehicleMileageAddSet As IMsgSetRequest
Set VehicleMileageAddSet = SessionManager.CreateMsgSetRequest("US", 6, 0) Dim
VehicleMileageAdd As IVehicleMileageAdd
Set VehicleMileageAdd = VehicleMileageAddSet.AppendVehicleMileageAddRq
VehicleMileageAdd.VehicleRef.FullName.setValue "Land Lugger" VehicleMileageAdd
.CustomerRef.FullName.setValue "Phillipe
Montreaux" VehicleMileageAdd.ItemRef.FullName.setValue "Delivery Fee"
VehicleMileageAdd.ORVehicleMileageAdd.OdometerReadingAdd.OdometerStart.setValue 1200
VehicleMileageAdd.ORVehicleMileageAdd.OdometerReadingAdd.OdometerEnd.setValue 1400
VehicleMileageAdd.BillableStatus.setValue bsBillable
Dim VehicleMileageAddResp As IMsgSetResponse
Set VehicleMileageAddResp = SessionManager.DoRequests(VehicleMileageAddSet)
SessionManager.EndSession
SessionManager.CloseConnection

When you query for vehiclemileage transactions and use a TxnDateRangeFilter, the From and To dates that you specify are assumed to be the Trip End dates, so the filter will filter for the Trip End date values that satisfy your filter range.

Vehicle mileage transactions can be queried and deleted like other transactions, and are subject to the same rules and limitations. For more information, see these chapters: Chapter 8, “Creating Queries,” and Chapter 10, “Modifying and Deleting Transactions and List Objects.”

Mileage transactions can be modified in the UI, but currently cannot be modified via the SDK.

Vehicles are simple items, and the SDK allows you to add them, modify them, and query for them.

Adding a Vehicle in qbXML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<?xml version="1.0"?>
<?qbxml version="6.0"?>
<QBXML>
    <QBXMLMsgsRq onError="continueOnError">
        <VehicleAddRq requestID = "UUIDTYPE">
            <VehicleAdd>
                <Name>Ford Romper</Name>
                <IsActive>true</IsActive>
                <Desc>flatbed</Desc>
            </VehicleAdd>
        </VehicleAddRq>
    </QBXMLMsgsRq>
</QBXML>