Item bundles using groups

An Item bundle is a container for a collection of items with a quantity that applies separately to each item. Group items that are often sold together into bundles so they can be added all at once to a transaction. For example, you sell a Deluxe Fountain that includes 2 pumps, 1 fountain, lighting, and installation. Here, the bundle is the Deluxe Fountain; the bundle items are pumps, fountain, lighting, and installation. Now, instead of adding each individual item that comprises a Deluxe Fountain into an invoice or sales receipt, you can simply add the Deluxe Fountain Item bundle. This eliminates the chance of errors when each item is entered and also provides a convenient framework for including a package discount.

What you need to know:

The Item resource is used to manage bundles.
Item bundles have the Item.type attribute set to Group.
The QuickBooks Online API supports read and query opertions, only.
Create and update bundles via the QuickBooks Online UI.
Item bundles can not contain other bundles.
Item bundles can not contain categories (Item.type = Category).
An item can be listed in the bundle more than once with same or different quantities.
Item bundle objects can be added to sales transactions via the GroupItemLine line type.
Item bundle objects in purchase transactions are not supported.

Managing item bundles

The table below outlines support for various Item bundle operations.

	Create	Update	Deactivate	Read and Query
QuickBooks Online UI	√	√	√	√
QuickBooks Online API	not supported	not supported	not supported	√

Creating an item bundle

Create Item bundles from the QuickBooks Online UI, only. Creating them via the QuickBooks Online API is not supported. Click on the animation to the left to see how to create the Deluxe Fountain bundle with the following items:

Two pumps
One fountain
Lighting
Installation

Resulting object:

{
   "Name": "Deluxe Fountain",
   "Sku": "234",
   "Active": true,
   "FullyQualifiedName": "Deluxe Fountain",
   "Taxable": false,
   "UnitPrice": 0,
   "Type": "Group",
   "PurchaseCost": 0,
   "TrackQtyOnHand": false,
   "PrintGroupedItems": true,
   "ItemGroupDetail": {
      "ItemGroupLine": [{
          "ItemRef": {
            "value": "5",
            "name": "Rock Fountain",
            "type": "Inventory"
          },
          "Qty": 1
      }, {
          "ItemRef": {
            "value": "11",
            "name": "Pump",
            "type": "Inventory"
          },
          "Qty": 2
      }, {
          "ItemRef": {
            "value": "8",
            "name": "Lighting",
            "type": "Service"
          },
          "Qty": 1
      }, {
          "ItemRef": {
            "value": "7",
            "name": "Installation",
            "type": "Service"
          },
          "Qty": 1
      }]
   }
}

Using item bundles

Once created, Item bundles are available for use in sales transactions.

Via the QuickBooks Online UI—add the bundle to a line. The individual members of the bundle unroll into the transaction appropriately.
Via the QuickBooks Online API—add the bundle with GroupLineDetail line detail type to the list of lines for the transaction. The GroupLineDetail detail type is, itself, an array of SalesItemlineDetail elements representing the members of the bundle.

{
   "Invoice": {
      "Deposit": 0,
      "AllowIPNPayment": false,
      "AllowOnlinePayment": false,
      "AllowOnlineCreditCardPayment": false,
      "AllowOnlineACHPayment": false,
      "domain": "QBO",
      "sparse": false,
      "Id": "162",
      "SyncToken": "0",
      "MetaData": {
         "CreateTime": "2016-09-27T10:40:53-07:00",
         "LastUpdatedTime": "2016-09-27T10:40:53-07:00"
      },
      "CustomField": [{
         "DefinitionId": "1",
         "Name": "Crew #",
         "Type": "StringType"
      }, {
         "DefinitionId": "2",
         "Name": "Shift #",
         "Type": "StringType"
      }],
      "DocNumber": "1047",
      "TxnDate": "2016-09-27",
      "CurrencyRef": {
         "value": "USD",
         "name": "United States Dollar"
      },
      "ExchangeRate": 1,
      "LinkedTxn": [],
      "Line": [{
         "Id": "1",
         "LineNum": 1,
         "Amount": 0,
         "DetailType": "GroupLineDetail",
         "GroupLineDetail": {
            "GroupItemRef": {
               "value": "22",
               "name": "Deluxe Fountain"
            },
            "Quantity": 1,
            "Line": [{
               "Id": "2",
               "LineNum": 2,
               "Description": "Rock Fountain",
               "Amount": 275.0,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "5",
                     "name": "Rock Fountain"
                  },
                  "UnitPrice": 275,
                  "Qty": 1,
                  "TaxCodeRef": {
                     "value": "TAX"
                  }
               }
            }, {
                  "Id": "3",
                  "LineNum": 3,
                  "Description": "Fountain Pump",
                  "Amount": 30.0,
                  "DetailType": "SalesItemLineDetail",
                  "SalesItemLineDetail": {
                     "ItemRef": {
                        "value": "11",
                        "name": "Pump"
                     },
                     "UnitPrice": 15,
                     "Qty": 2,
                     "TaxCodeRef": {
                        "value": "TAX"
                     }
                  }
            }, {
               "Id": "4",
               "LineNum": 4,
               "Description": "Garden Lighting",
               "Amount": 0,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "8",
                     "name": "Lighting"
                  },
                  "UnitPrice": 0,
                  "Qty": 1,
                  "TaxCodeRef": {
                     "value": "TAX"
                  }
               }
            }, {
               "Id": "5",
               "LineNum": 5,
               "Description": "Installation of landscape design",
               "Amount": 50.0,
               "DetailType": "SalesItemLineDetail",
               "SalesItemLineDetail": {
                  "ItemRef": {
                     "value": "7",
                     "name": "Installation"
                  },
                  "UnitPrice": 50,
                  "Qty": 1,
                  "TaxCodeRef": {
                     "value": "NON"
                  }
               }
            }]
         }
      }, {
         "Amount": 355.0,
         "DetailType": "SubTotalLineDetail",
         "SubTotalLineDetail": {}
      }],
      "TxnTaxDetail": {
         "TotalTax": 0
      },
      "CustomerRef": {
         "value": "4",
         "name": "Diego Rodriguez"
      },
      "CustomerMemo": {
         "value": "Thank you for your business and have a great day!"
      },
      "BillAddr": {
         "Id": "5",
         "Line1": "321 Channing",
         "City": "Palo Alto",
         "CountrySubDivisionCode": "CA",
         "PostalCode": "94303",
         "Lat": "37.443231",
         "Long": "-122.1561846"
      },
      "ShipAddr": {
         "Id": "5",
         "Line1": "321 Channing",
         "City": "Palo Alto",
         "CountrySubDivisionCode": "CA",
         "PostalCode": "94303",
         "Lat": "37.443231",
         "Long": "-122.1561846"
      },
      "SalesTermRef": {
         "value": "3"
      },
      "DueDate": "2016-10-27",
      "TotalAmt": 355.0,
      "HomeTotalAmt": 355.0,
      "ApplyTaxAfterDiscount": false,
      "PrintStatus": "NeedToPrint",
      "EmailStatus": "NotSet",
      "BillEmail": {
         "Address": "Diego@Rodriguez.com"
      },
      "Balance": 355.0,
      "HomeBalance": 355.0
   },
   "time": "2016-09-27T13:19:18.581-07:00"
}

Considerations for existing apps

QuickBooks companies have recently been enabled for Item bundles and as a result, they could start appearing in your user’s sales transactions. Currently, your app handles transactions containing a list of lines with a DetailType of SalesItemLine being the most common type, referencing an Item object and quantity. With bundles, there is an additional DetailTypeof GroupLineDetailthat includes the bundle name and a nested array of lines representing the members of the bundle.

Now, consider some of the things that can happen in your app when it sees this new line type:

If the app ignores the GroupItemLineDetail type line entirely, your app shows 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.
If the app updates this transaction ignoring the GroupItemLineDetail line, the group line is completely stripped out and the user purchasing the assembled bundle is suddenly getting an empty box because the order just has a description and a subtotal line.

Best practices when reading transactions

Minimum support: In the event the user asks your app to take action on a transaction that contains a group line, the app recognizes that a transaction contains a group line and lets the user know it doesn’t support bundles
Full support: Your app properly handles the details of the transaction, including the group lines and their details.

Best practices when creating transactions

Minimum support: If the user takes action that would cause an Item bundle to be added to a sale, and the app isn’t ready to support bundles yet, the app should provide the user with a polite warning that it doesn’t support bundles yet and not add the bundle to the sale.
Full support: If your app is creating transactions in QuickBooks Online based on user input and it provides a form for data entry similar to QuickBooks Online sales forms, the Item bundle should behave the same way in your app’s UI as it does in QuickBooks Online. That is:
- If a user chooses an Item bundle, unroll the bundle into the app’s form the same way QuickBooks Online does.
- If the user modifies the quantity on the bundle line, your app needs 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, your app removes the line appropriately but maintains the bundle, similarly on the quantity.