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:

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

qbo/docs/develop/tutorials/CreateBundle.gif

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
   "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.
qbo/docs/develop/tutorials/ItemBundle.jpg

Example of an invoice object that specifies the Rock Fountain item bundle:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
{
   "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.