Departments

QuickBooks Online has Departments (its name for locations). QuickBooks Desktop does not: its one dimension for slicing a company file is the class. Out of the box, Department is therefore unsupported and fails loud with 422 UNSUPPORTED_BY_DESKTOP.

If your Desktop company file already uses classes the way a QBO company uses departments, turn on Departments from classes and TenkeyBridge serves Department as an alias of Class. It is off by default, it is chosen per company file, and with it off nothing about your API behaves differently.

Turn it on

• Portal: open the company file, find the Departments card, tick Use QuickBooks classes as departments. Available to organization admins and owners, and on your sandbox.
• Admin API: PATCH /admin/v1/realms/{realmId}/settings with {"departmentsFromClasses": true} (see the Admin API).

The change reaches every gateway machine within about 15 seconds.

What changes when it is on

QBO call	What TenkeyBridge does
GET /department/{id}, SELECT ... FROM Department	Reads the class and returns it as a Department.
POST /department	Creates a class. ParentRef makes a sub-class.
POST /department with Id + SyncToken	Updates the class (sparse: Name, Active, ParentRef). Deactivate with Active: false.
POST /department?operation=delete	Still 422: a class cannot be deleted through QuickBooks Desktop.
DepartmentRef on a transaction (write)	Becomes the transaction's header ClassRef.
DepartmentRef on a transaction (read)	Filled in from the header ClassRef. ClassRef is returned too.
Preferences	AccountingInfoPrefs.TrackDepartments is true.
Batch and CDC	Work the same: Department is served from classes.

A Department looks like the QBO object:

{
  "Department": {
    "Id": "80000005-1767225600",
    "SyncToken": "1767225600",
    "Name": "East",
    "FullyQualifiedName": "Regions:East",
    "SubDepartment": true,
    "ParentRef": { "value": "80000004-1767225600", "name": "Regions" },
    "Active": true,
    "MetaData": { "CreateTime": "2026-01-01T00:00:00Z", "LastUpdatedTime": "2026-01-01T00:00:00Z" }
  }
}

Its Id is the class's Id: Department/{id} and Class/{id} are the same record. SubDepartment and FullyQualifiedName are read-only (they follow ParentRef). A class name is at most 31 characters.

DepartmentRef on transactions

QuickBooks Desktop has a header-level class on Invoice, SalesReceipt, Estimate, CreditMemo, PurchaseOrder and TimeActivity. On those, DepartmentRef and the header ClassRef are the same field:

POST /v3/company/{realmId}/invoice
{
  "CustomerRef": { "value": "80000002-1767225600" },
  "DepartmentRef": { "value": "80000005-1767225600" },
  "Line": [ ... ]
}

• Send DepartmentRef or ClassRef. Sending both with the same value is fine (it is what you get from echoing back a record you read).
• Sending both with different values is 400 BAD_REQUEST and nothing is written. It is a loud error on purpose: they are one field, so picking one silently would lose data.
• A ClassRef on a line (SalesItemLineDetail.ClassRef) is separate and unaffected.
• Bill, Purchase, VendorCredit, JournalEntry, Deposit, RefundReceipt and Transfer have no header class in QuickBooks Desktop (the class lives on each line). DepartmentRef on them is 422 UNSUPPORTED_BY_DESKTOP; set ClassRef on the lines instead.
• In a query, WHERE DepartmentRef = '...' filters on the header class.

With it off

Department routes return 422 UNSUPPORTED_BY_DESKTOP, and DepartmentRef on a transaction is UNMAPPED_FIELD, exactly as before. TrackDepartments reads false.

Things to know

• Turning it off does not change any data: classes stay classes, and records that were written with a DepartmentRef keep their class.
• It is one dimension. If a company file uses classes for something other than locations, Department will list those classes too. Turn the setting on only when classes are your departments.
• Hidden classes follow the usual rule: list them with Active in (true, false).
• Attachable has no Desktop equivalent at all, is not stored by TenkeyBridge, and has no opt-in. It returns 422 UNSUPPORTED_BY_DESKTOP; keep files in your own system keyed by the record's Id.

See also

• Compatibility matrix: Department, Class, Preferences
• Admin API and the Developer portal
• Error codes