Item hierarchies using categories

Categories are used to create a hierarchical organization of the things the company sells. They allow placing products in intuitive groups, making it easy to keep the company’s list of products and services organized and allowing you to easily find items to add to transactions. For example, it is intuitive to look for Men’s Jeans under Apparel->Jeans.

Key changes

Items used as parent items and things the company sells can no longer be freely mixed.
- An app can now clearly distinguish between things the company sells and categories used to build a hierarchy to organize them.
- Categories do not have a price, income account, or expense accounts.
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.
IDs of current Item objects are preserved, but may be pushed down in the hierarchy after migration. See Migration process for further information.
New categories and subcategories are created with the same name for parent items to preserve the hierarchy.
The Item resource is used to manage both the things you sell and their category hierarchy. Use the new Item resource type of Category to define category levels in the hierarchy.
Use the minorversion=4 query parameter with Item resource URIs to access categories. If you access Category type items with minor versions earlier than 4, they are returned with Item.Type set to Service. They are not sellable and you receive an error if you include them in a transaction.
Full information about Category objects and supported CRUD methods is available on the Item resource page of the API Reference Guide.

Activating categories in sandbox companies

You must explicitly activate categories in your sandbox company via the QuickBooks user interface before you can access the functionality. Sign in to your QuickBooks Online sandbox account and perform the following:

Click on company settings gear icon on the top right of the screen and select Products and Services.
On the Products and Services page, click on the Activate Now link in the information box.
Click on the Activate Now button to activate categories and initiate item migration from sub-items to categories in your sandbox company.

Activate forces a page refresh so that the Products and Services list correctly shows categories instead of sub-items.

Migration

Migration process

How existing Item objects are migrated

Developers do not have to migrate any existing Item objects to the new hierarchy system, as this migration is done automatically. However, what developers need to do is to ensure their code is working for the new system.

Only lowest level child items are referenced in transactions

In the diagram below, Items A, B, C, D are parent items and Item E is the lowest level child item. If only Item E is used in transaction, A, B, C, and D migrate to categories (Item.Type=Category); E migrates as an item (Item.Type!=Category).

Child and parent items are both referenced in transactions

In the diagram below, Items A, B, C, D are parent items and Item E is the lowest level child item. If all items A-E are possibly referenced in transactions regardless of relationship, Items A, B, C, and D are created as categories (Item.Type=Category) and Items A-E are migrated as children under their respective categories (Item.Type={Inventory,NonInventory,Service}), maintaining original IDs. Notice both Item D and Item E are children of Category D.

../../../_images/MigrateChildAndParent.png

Note

Note

If using minorversion=4 and your app detects a company has become category enabled (see coding guidelines below) since it last accessed Item objects, then perform a full sync and refresh of Item objects. This is to ensure that accesses to Item objects based on your former item hierarchy map to the updated one. Issue the following URI:

GET https://QuickBooks.API.intuit.com/v3/company/<realmId>/query?query=select * from Item MAXRESULTS 1000

The maximum number of objects that can be returned in a response is 1000.
If MAXRESULTS is not specified, the default number returned is 100.
If a query returns many objects, fetch them in chunks, as described in Pagination.
To determine the number of objects that a particular query returns, query with COUNT (*) as follows:

GET https://QuickBooks.API.intuit.com/v3/company/<realmId>/query?query=select COUNT(*) from Item

Coding guidelines

Inventory operation	Required code changes
Determine if company is category enabled.	`GET https://QuickBooks.API.intuit.com/v3/company/<realmId>/companyinfo/<realmId>?minorversion=4` Test `CompanyInfo.NameValue.Name.ItemCategoriesFeature` flag: - `true`—enabled for categories - `false`—not enabled for categories
Operations on individual, non-category Item objects	None. Existing code works.
Access a category.	`GET https://QuickBooks.API.intuit.com/v3/company/<realmId>/item/<itemId>?minorversion=4`
Create category.	`POST https://QuickBooks.API.intuit.com/v3/company/<realmId>/item?minorversion=4` Sample request: { “Name”: “Flowers”, “Type”:”Category” }
Create a new Inventory, NonInventory, or Service object as child of category	Use the create operation. Parent must be of type Category. `POST https://QuickBooks.API.intuit.com/v3/company/<realmId>/item?minorversion=4` Set Item.Type to one of {Inventory Set Item.SubItem to true. Set Item.ParentRef to a Category.	Service	NonInventory}.
Create a new Inventory, NonInventory, or Service object as a sub item of a non-category.	Not supported. Service returns an error. .. container:: code-sample .. code-block:: json :name: codeblock1 :linenos: { “Fault”: { “Error”:[ { “Message”:”A business validation error has occurred while processing your request”, “Detail”:”Business Validation Error: This selection can only be a Category.”, “code”:”6000”, “element”:”” } ], “type”:”ValidationFault” }, “time”:”2015-09-21T10:55:36.342-07:00” }
Assign an existing Inventory, NonInventory, or Service object to a category.	Use the update operation. Parent must be a category. `POST https://QuickBooks.API.intuit.com/v3/company/<realmId>/item?minorversion=4` Set `Item.Type` to {Inventory Set `Item.SubType` to true. Set `Item.ParentRef` to a Category.	Service	NonInventory}.

Considerations for existing integrations

For existing apps that are not minorversion=4 enabled, understand how they behave when a QuickBooks Online company is enabled for categories. Here are some situations to consider:

Situation	Consideration
Looking up an item by `Item.Name` only.	The automatic migration process creates item categories to mimic the existing hierarchy, and then populates the new category with existing item objects resulting with existing item objects and new categories having the same name. Be cautious that your app doesn’t pick an item object that is really a category because you’ll get an error when you put that in a transaction. In fact, this holds for `minorversion=4` too. When you use `minorversion=4` you have the hint of the `Item.Type`, as well, and when you search for a sellable item object with a name that matches an item object in your system, you should filter to not get categories. Error returned when a category is used in a transaction: .. container:: code-sample .. code-block:: json :name: codeblock2 :linenos: { “Fault”: { “Error”: [{ “Message”: “A business validation error has occurred while processing your request”, “Detail”: “Business Validation Error: Categories cannot be used in transactions.”, “code”: “6000”, “element”: “” }], “type”: “ValidationFault” }, “time”: “2015-09-21T10:51:50.512-07:00” }
Allowing users to create an item and to choose its parent in the hierarchy.	Be prepared for the possibility of an error if your code allows the user to put items in the hierarchy and they try to make a new sellable item a child of an existing sellable item. When you switch to `minorversion=4` and you let the user choose the parent of an existing item, filter for those items whose `Item.Type` is category. Error when referencing a sellable item as a parent: .. container:: code-sample .. code-block:: json :name: codeblock3 :linenos: { “Fault”: { “Error”:[ { “Message”:”A business validation error has occurred while processing your request”, “Detail”:”Business Validation Error: This selection can only be a Category.”, “code”:”6000”, “element”:”” } ], “type”:”ValidationFault” }, “time”:”2015-09-21T10:55:36.342-07:00” }

Error messages

Code	Message/Detail	Notes
1020	Message: Update Failed Detail: Update Failed : The Category Item type does not support soft delete with Active=false; use Operation=Delete to Hard Delete a Category	Error returned after attempt to update `Item.Active` to `false`.
6000	Message: A business validation error has occurred while processing your request \| Detail: Business Validation Error: Categories cannot be used in transactions.	Error returned when a category is used in a transaction.
6000	Message: A business validation error has occurred while processing your request \| Detail: Business Validation Error: This selection can only be a Category.	Error returned when attempt to create a new Inventory, NonInventory, or Service object as a sub item of a non-category.
6000	Message: A business validation error has occurred while processing your request \| Detail: Business Validation Error: You can’t change a Category into another item type.	Items initially defined as categories must remain categories.
6000	Message: A business validation error has occurred while processing your request \| Detail: Business Validation Error: No more than four Category levels are allowed.	Sub-categories can be nested to a maximum depth of three levels below a top-level category.