Developers who have been in the QuickBooks ecosystem for a long time might recall the QuickBooks Desktop concept of a “Group Item”. Coming to your developer sandbox this month is the QuickBooks Online equivalent of this. In the QuickBooks Online UI, we refer to this as a “Bundle” item; however, in the v3 API, the schema (designed to support both desktop and online use-cases) still uses the “Group” terminology. Because these features have been a part of the V3 spec from day 1, no minorVersion is required to access the features. But this imposes some responsibility on your apps!
If you are a developer working with sales transactions or items in QuickBooks, it is critical that you understand these changes and test your application against sandbox as soon as this feature goes live for our sandboxes later this month. This article discusses what a bundle is and how it can affect your applications.
OK, so what’s a “Bundle”?
The easiest way to understand bundle items is to consider a concrete use case. Imagine a gift basket:
- 2 chocolate bunnies
- 1 Bag of jelly beans
- 1 box of marshmallow chicks
- 1 Pez dispenser
- 2 packages assorted Pez candy
- 1 plush bunny
- 1 medium basket
- 1 package plastic grass
If I run a gift shop and my cashiers have to add each individual item and quantity into an invoice or sales receipt, there are going to be a lot of mistakes and incorrect prices. Also, I might also want to include a discount just to get some of those nasty marshmallow chicks off my shelves!
Bundle items to the rescue! I can simply define a bundle item “Gift Basket” and define the items and quantities that belong to the bundle.
Then, when I create an invoice or sales receipt and create a line using the bundle item, the individual members of the bundle “unroll” into the transaction appropriately. As I change the quantity of the bundle item, the quantities of the individual members change appropriately as well:
Further, my customers might have specific likes and dislikes or allergies that need to be observed, so we might need to take some things out of the bundle. For example, perhaps my customer loves those marshmallow chicks as much as I hate them, and wants to get four boxes instead of just one, but doesn’t want the Pez candy at all. No problem! I can just edit the quantity on the marshmallow chicks line and remove the Pez stuff entirely:
The important thing to note is that this is still a sale of a bundle item, even though we customized the bundle. Another important thing is that, if I alter quantities on the bundle, all the bundle components are updated immediately. These features are what makes this much more than just a simple shortcut in the UI; it is a real concept in QuickBooks that affects some of the sales reports (sales by item, for example).
The fact that the bundle “unrolls” into the transaction is also what separates the “bundle” concept from a related (but very different) concept that QuickBooks desktop also has (but QuickBooks online does not yet have): the “Assembly”. When you sell a completed “assembly”, only one line for the assembly itself (e.g., a Volagi Liscio 2 bicycle) appears on the sales transaction. Putting that assembly together from its bill of materials (BOM) is a separate transaction that decrements inventory of the individual items in the BOM (frame, handlebars, brakes, derailleurs, etc.) and increments inventory of the finished bicycle.
Nice feature! Why do I care as a Developer?
Because of the importance of maintaining the identity of a bundle item (even if it is customized) in a sales transaction, we can start to see that the transaction model becomes a bit more complex and we, as developers working with transactions, need to preserve that integrity. The V3 API schema has always had support for bundles because it supports QuickBooks desktop data as well as QuickBooks Online data; but because QuickBooks Online hasn’t had bundle (group) items before now, you might not have realized that you need to handle these cases and this nested data.
Let’s start with the transactions themselves. You are used to transactions containing a list of lines with a DetailType telling you what kind of detail object to look for, with SalesItemLines being the most common type, referencing an item and quantity, etc.:
What’s different with bundles is that now we have another DetailType that matters — “GroupLineDetail” — and that line might itself include a list of lines! Consider that Basket line, above; that’s really just the basket, not all the stuff that goes into the basket. So here’s what we’d see if we had that same transaction, but instead used the group item for the gift basket. Note the “Line” array within the GroupLineDetail, and also note that the actual total ($142) for the whole basket is in a subtotal line that follows the GroupLine:
Now, consider what would happen in your application when you see this line! Worst case: you see the GroupItemLineDetail type and ignore the line entirely, you show a transaction to the user that is completely missing a line, and the total of the remaining lines doesn’t add up to the amount of the transaction! Even worse, if you modify this transaction and send it back to QuickBooks, you’ll completely strip the group line out and the customer purchasing the assembled “Allure” is suddenly getting an empty box because the order just has a description and a subtotal line!
So, what’s an application that reads or modifies sales transactions to do?
- Bare minimum: Recognize that a transaction contains a group line and let the user know you don’t support bundles if they ask you to take action on a transaction that contains a group line.
- Full support: Properly handle the details of the transaction, including the group lines and their details.
On the create side, there’s less risk to a customer’s data, but there are some nuances to be aware of, especially with our early release to sandbox to support getting you access to this feature before our customers have it.
- Bare minimum: If the user takes action that would cause a bundle item to be added to a sale, and you aren’t ready to support bundles yet, you should provide the user with a polite warning that you don’t support bundles yet and not add the bundle to the sale.
- Full support: If you are creating transactions in QuickBooks based on user input and you provide a form for data entry similar to QuickBooks sales forms, you want the bundle item to behave the same way in your UI as it does in ours:
- If a user chooses a bundle item, you need to “unroll” the bundle into your form the same way QuickBooks does. If the user modifies the quantity on the bundle line, you need to do the appropriate multiplication on the individual lines of the bundle. If the user removes a line or changes the quantities on a line, you need to remove the line appropriately but maintain the bundle; similarly on the quantity.
Once we get to production availability (vs. sandbox availability) you can do a round trip to QuickBooks to get the bundle unrolled (save the transaction with the quantity and bundle item reference and the response will include the unrolled bundle). Quite frankly, if you are showing the lines in a UI of your own, you probably want to do the unroll yourself anyway! But if it’s an e-commerce app or something like that, you don’t necessarily need to unroll until the data is sent to QuickBooks.
Leave a Reply