TenkeyBridge
← Back to blog

Item Groups on QuickBooks Desktop: What QBO Bundles Don't Prepare You For

  • quickbooks item group api
  • quickbooks desktop bundle api
  • groupLineDetail quickbooks
  • purchase order item group quickbooks desktop
Isometric illustration of an open carton holding four smaller cartons, with one lifted out on a thin green line.

Quick answers

  • Do QuickBooks Desktop item groups map to QBO bundles? Yes — on sales and expense forms a Desktop item group arrives as a line with DetailType: "GroupLineDetail", the same shape a QBO bundle uses.
  • Is group quantity already applied to component lines? Yes. Component quantities come back multiplied by the group quantity, so don't multiply again.
  • How do I write an item group to a purchase order? Send a group line in Line; as of October 2026 TenkeyBridge translates it to PurchaseOrderLineGroupAdd for you.
  • Why does a partial group update return 400? A whole-array Line update treats a group as all-or-nothing: list every component line to keep the group, omit all of them to delete it, anything in between is rejected.
  • Can I edit one component of a group? Only by resending every component in that group — Desktop deletes components you leave out.

The case that starts this

ExampleCo sells an "Install Kit": a bracket, two cable runs, a labor line, and a consumable. In QuickBooks Online it's a bundle. Pat Owner's team built the integration against QBO two years ago, it reads invoices, it writes invoices, and the bundle handling is forty lines of code nobody has touched since.

Then ExampleCo's biggest customer is on QuickBooks Desktop Enterprise, and the same forty lines get pointed at a Desktop company file.

The reads are fine. The invoice comes back with a GroupLineDetail line, the component lines are right there inside it, the totals foot. Ship it.

The purchase orders are where it stops being fine. Someone edits the quantity on the bracket inside the Install Kit group on an open PO, the integration sends what it believes is a surgical update, and the other four component lines vanish from the PO in QuickBooks. Or — if you're luckier — the request comes back 400 and nothing changes at all.

That gap between "reads are fine" and "writes have different rules" is the whole subject of this post.

What the read looks like

On an invoice, a Desktop item group surfaces the way a QBO bundle does. One parent line with DetailType: "GroupLineDetail", a GroupLineDetail object naming the group item and its quantity, and a nested Line array holding the components:

{
  "LineNum": 1,
  "DetailType": "GroupLineDetail",
  "GroupLineDetail": {
    "GroupItemRef": { "value": "42", "name": "Install Kit" },
    "Quantity": 3,
    "Line": [
      {
        "LineNum": 1,
        "DetailType": "SalesItemLineDetail",
        "Amount": 45.00,
        "SalesItemLineDetail": {
          "ItemRef": { "value": "17", "name": "Bracket" },
          "Qty": 3,
          "UnitPrice": 15.00
        }
      }
    ]
  }
}

Two things to notice before you write any mapping code.

The group quantity is already baked into the components. The group quantity is 3, the bracket is one-per-kit, and the component Qty reads 3 — not 1. QuickBooks Desktop expands the group on the transaction itself; what you're reading is the expanded result, not the template. If your QBO code multiplies component quantity by group quantity to get a physical count, you will get nine brackets for three kits. This is one of those bugs that doesn't show up in the totals, because the amounts are right. It shows up in your warehouse.

The parent line's amount behavior depends on the group's print setting. A Desktop group item can be set to print its components on the form or to print as a single summarized line. That setting affects what appears on the document, not what you read back — the components are in the payload either way. Don't infer the print setting from the API response; if you need it, read it off the group item.

Expense forms — bills, checks, credit card charges — carry group lines the same way: GroupLineDetail, nested components, group quantity applied. Which is to say, if you already handle GroupLineDetail for QBO bundles, your read path is mostly done. Check the compatibility matrix for the per-entity detail before you assume a specific form is covered.

Where Desktop and QBO stop agreeing

QBO bundles are a presentation and pricing convenience layered over line items. Desktop item groups are closer to a macro: the group expands into real component lines on the transaction, and after expansion, those component lines are the transaction. The group identity survives, but what QuickBooks stores and validates is the expanded set.

That difference is invisible on read and loud on write.

In the QBO API you can send a group line and reason about it as a unit. On Desktop, the underlying SDK has separate add and modify verbs for group lines, and the modify side has a rule that catches most teams off guard: a group modify replaces the component set. Components you don't include are not "left alone." They're gone.

TenkeyBridge doesn't paper over that. It can't — the behavior belongs to QuickBooks, and hiding it would mean silently inventing component lines on your behalf. What it does instead is translate the QBO-shaped request into the right Desktop verb and refuse requests that would produce a result you didn't ask for.

Purchase orders: what changed in October

Group writes on purchase orders went in during the October 2026 release, alongside the other write and report work in the October changelog. Three behaviors are worth knowing before you send one.

1. Creates go through PurchaseOrderLineGroupAdd

You send a line with GroupLineDetail; TenkeyBridge emits a PurchaseOrderLineGroupAdd rather than a flat item line. You do not need to enumerate components on create — QuickBooks expands the group from the item definition:

POST /v3/company/{realmId}/purchaseorder

{
  "VendorRef": { "value": "9" },
  "Line": [
    {
      "DetailType": "GroupLineDetail",
      "GroupLineDetail": {
        "GroupItemRef": { "value": "42" },
        "Quantity": 3
      }
    }
  ]
}

Read the PO back after the create. The response carries the expanded components, with quantities already multiplied by the group quantity, and those component line identifiers are what you'll need for any later edit.

2. Updates send the whole Line array, and the group folds back

A PO update is a full-replacement write: you send the complete Line array you want the document to end up with. For group lines, TenkeyBridge folds the component lines you send back into their parent group before handing the request to QuickBooks. The folding rule is all-or-nothing per group:

| What you send for a group | Result | | --- | --- | | Every component line present | Group kept, modified as sent | | All component lines omitted | Group deleted from the PO | | Some present, some missing | 400 — request rejected, nothing written |

The third row is the one that matters. A partial component set is the exact shape that would cause Desktop to silently drop the lines you left out, so it's rejected before it reaches the company file. The 400 is doing you a favor; treat it as a signal that your line array is incomplete, not as a transient error to retry. (For how other Desktop failures map onto QBO-style fault bodies, see Decoding QuickBooks Desktop Errors.)

3. Component edits mean resending every component

Put the two previous points together and the workflow for "change the bracket quantity from 3 to 4" is:

  1. GET the purchase order.
  2. Take the full Line array as returned, including every component of every group.
  3. Change the one field you care about on the one component.
  4. PUT the whole array back.

Not a diff. Not just the group you touched. The whole array, with every component of every group intact.

If your QBO code already does read-modify-write on the full line array, you're in good shape — that's the same discipline described in Sparse Updates vs. Full Replacement. If it builds a minimal patch, group lines are where that strategy stops working, and the fix is to widen the read before the write rather than to narrow the write.

One practical note: between your GET and your PUT, someone in the QuickBooks UI may have edited the same PO. Full-array replacement means you'd overwrite their change. Use the SyncToken you got on read; a stale token fails the write rather than clobbering the edit.

A short checklist for group support

If you're bringing an existing QBO integration to a Desktop file and groups are in scope:

  • Read path: handle DetailType: "GroupLineDetail" and nested Line. You likely already do.
  • Quantities: do not multiply component quantity by group quantity. It's applied.
  • Creates: send the group line with GroupItemRef and Quantity; let QuickBooks expand it. Read back to learn the component lines.
  • Updates: read, mutate, send the full array. Every component of every group, every time.
  • Deletes: omit all of a group's components to remove it. Omitting some is a 400.
  • Inventory assemblies are not groups. An assembly is a stocked item that builds from components; a group is a line-expansion shortcut with no inventory of its own. They read differently and they are not interchangeable — if ExampleCo's "Install Kit" is an assembly in the Desktop file, none of the above applies and you're handling a plain item line.
  • Check the matrix per entity. Group write coverage is not uniform across every transaction type. The Invoice and PurchaseOrder pages in the Desktop compatibility docs say what's supported today; believe them over this post if they ever disagree.

What we're still honest about

Group support is deliberately conservative. The 400 on a partial component set is a choice: Desktop would have accepted that request and quietly deleted lines, and we'd rather hand you an error you can read than a company file you have to reconcile. The cost is that naive patch-style clients break loudly on their first group update. We think that's the right trade, but it is a trade, and you should know which side of it you're on before you ship.

Coverage also varies by entity and by QuickBooks edition. The honest answer to "does it work on form X" is to look it up rather than to generalize from invoices and purchase orders — which is why the compatibility matrix is per-entity rather than a checkmark on a feature page.

FAQ

How do item groups appear on a Desktop invoice read?

As a single line with DetailType: "GroupLineDetail", containing a GroupItemRef, the group Quantity, and a nested Line array of the expanded components. Component quantities already reflect the group quantity. The same shape appears on expense forms such as bills and checks.

How do I change one component of a group on a purchase order?

Read the purchase order, modify the one component field in the returned Line array, and send the entire array back with the current SyncToken. Every component of every group must be present in that array, including groups you didn't touch.

Why did my partial group update return 400?

Because you sent some but not all of a group's component lines. QuickBooks Desktop would interpret that as "delete the components I omitted," so the request is rejected instead of being written. Re-read the transaction, include the full component set, and resend.

Are inventory assemblies handled the same way as item groups?

No. An assembly is a stocked inventory item built from components and behaves on a transaction like any other item line — no GroupLineDetail, no component array. Groups expand into lines; assemblies don't.

Can I create a new item group definition through the API?

That's an item-level question rather than a transaction-level one, and coverage differs from posting group lines on transactions. Check the item entity pages in the compatibility docs before building against it.

Does a group line change how batch requests behave?

Not specially, but the usual caveat applies: a batch isn't a transaction, so one group line failing won't roll back the others. Handling partial failure on Desktop covers the pattern. If you want to see a GroupLineDetail round-trip against a real company file without wiring anything up, the sandbox and the quickstart are the fastest path.