By now youve probably heard about the changes coming to QuickBooks Products & Services list — and available today for you to preview and experiment with in developer sandboxes. Given what I’ve heard from developers integrating with the QuickBooks Item resource over the past couple of years, for the most part, these changes should be a cause for celebration, as it should make it much easier for you to integrate your category/subcategory/product hierarchies with ours now.
But, there are a few things you need to be aware of now so you can test your application with the sandbox and determine the priority of moving your code to our minor version 4 QuickBooks API.
Changes in a nutshell
For the full details, you can read about item hierarchies using categories here. But let’s quickly review the changes we’re talking about.
Before these changes, QuickBooks treats everything in the item list as an item.
- You can have up to 5 levels of parent-child-grandchild relationships between items
- Every item knows the name and ID of its parent
- An item from any level of the hierarchy can have a price
- An item can be used on sales or purchase transactions
After these changes, QuickBooks now has a concept of a category, and hierarchies built with them have specific rules:
- Up to four category levels are supported, with an inventory, non-inventory, or service item as the fifth.
- Items–the things you sell–cannot have children. That is, if your items are organized into a hierarchy, items can only be at the leaf level of the hierarchy.
- A category cannot be used on a transaction; it’s there only for the purposes of categorizing/subcategorizing the things you buy and sell.
In order to minimize impact to the existing v3 services and to maintain some level of compatibility with existing apps, we expose the category object as part of the Item list. With minor version 4, the Item.Type field is set to Category, and, of course, the category item has no price and no sales or expense account associated with it.
Potential problem areas
Before we jump into the specifics, it’s worth sharing a little data analysis we did so that you can understand how many of your users might be impacted by these potential problem areas. Roughly 13% of our users have a hierarchical item list today. So 87% of our users have a purely flat item list, which won’t be impacted at all by these changes. Still, that’s a pretty important 13% that’s more likely to be connected to apps like yours, so you should look at data on your side as well to assess the # of users who might see an issue.
Even more importantly, you should understand these potential scenarios in your app and test against the sandbox environment to see if you are vulnerable to these issues; if you are, switch to using minor version 4 of the QuickBooks API sooner, rather than later.
Use of a Category item in a transaction will result in an error
As it happens, those basic characteristics (no price, no account associations) are how we’ve been recommending that you determine if an item was in the hierarchy for organization purposes or for use on a transaction before as well. So with minor version 3 and earlier, after the changes, we’ll continue to deliver categories to you in the item list (Item.Type set to Service because the minor version 3 and earlier spec didn’t have Category in the enum), but they are guaranteed to not have a price and to not have a sales or purchase account association. So, if you followed that advice, you won’t have an issue with using something in a transaction that’s no longer allowed. Similarly, before the changes, if an item didn’t have an account associated with it, you’d get an error when you tried to use the item in a transaction.
But if your app allowed it before, it’s possible that your code lets the user add what is really a category to a transaction in your system, and when your app tries to send that transaction to QuickBooks company, your app gets an error.
With minor version 4, for any situation that lets a user select items that are to be used in a transaction, filter by Item.Type in (Service, NonInventory, Inventory).
Attempting to make a sellable item (Service, NonInventory, or Inventory) the parent of another item (of any type) results in an error.
This should be less common than the first problem area, but if you allow users to change the hierarchy of items in your system–including creating a new item and designating its parent category/subcategory–and then try to push those changes to QuickBooks, but don’t enforce the same rules we now enforce, you get errors when you attempt to send those changes to QuickBooks.
In both of these cases, the error code is our generic business logic error code, and the error message you get is intended to be displayable to the user. So you receive a message you can present to the user when the error occurs. For example, “A category cannot be used in an invoice line” or “a sellable item cannot be the parent of another item.”
With minor version 4, you can ensure that when you present the list of potential parents for a new or existing item you filter to show only those items that have Item.Type=Category.
Finding items by name may discover duplicates
It’s always been true that item names themselves are not guaranteed to be unique, only the fullname of an item; that is, Cat:SubCat:Item is guaranteed unique, but user behavior being what it is, duplicate names even at just the name level are quite rare in QuickBooks data. The restructuring of the item hierarchy that is done when we migrate a user into item category functionality can create duplicate names where none existed before. Consider, for example, the situation where I used to have an item called running shoes and I sold all running shoes, regardless of brand or type under that one line item for some time before realizing I could get more insight from my data and track what sold well and what didn’t sell well if I broke things up a bit. So I created ASICS Gel Nimbus 17, Nike Air Zoom Pegasus, and Nike LunarGlide items, all with the Running Shoes item as a parent. After the migration of my company to item categories, I now have a category item called Running Shoes and an item (NonInventory since I never originally tracked inventory on Running Shoes in my business) named Running Shoes whose parent is Running Shoes. So the full name of the existing item that was used on all my old transactions is Running Shoes:Running Shoes and I still have Running Shoes:Nike LunarGlide, etc. If your app finds items by name and looks for an item named Running Shoes, it will now find two items, one which can be used on a transaction, the other which cannot.
With minor version 4, if you set your query for the item to filter by Item.Type not being a Category, you would avoid the problem. But pre minor version 4 code might run into trouble unless you were already distinguishing based on whether an item had a price and accounts.
The positive side
I mentioned earlier the positive side of these changes. With minor version 4, you can now import our items and categories with confidence. If you are an eCommerce or point of sale application, you can help bootstrap a new user’s store with all their items from QuickBooks. Since category is such a critical part of the e-commerce store navigation environment, you can import the categories and put the items into each category appropriately to get them started, and the user can then add additional categories for eCommerce navigation purposes and add additional categories to their items. QuickBooks still enforces a single category in this case, since categories in QuickBooks are used not just for navigation through the item list, but for reporting on sales by category, etc. You can know immediately, rather than guessing based on whether data is or is not populated in the item, whether an item is a category or a sellable product.
Further, with minor version 4, you get access to the long-awaited Item.Sku field, critical to many business workflows.
Got questions?
Ive been working with apps and QuickBooks for over 13 years now, and have been working closely with the QuickBooks Online inventory team. If you have questions or concerns about what’s being done here, please feel free to comment below or reach out via the developer forums. We’ll do our best to get you an answer quickly.
Leave a Reply