Accounting Account Type Hierarchy in Unified

Overview

Unified's accounting_account object normalizes chart-of-accounts structures across providers like QuickBooks Online (QBO) and Xero, while preserving each provider's account hierarchy for reporting, categorization, and downstream analytics.

Rather than adding provider-specific fields, Unified exposes the hierarchy through a single, extensible taxonomy array.

The Unified accounting account model

IAccountingAccount {
    id?: string;
    created_at?: (string | Date | number);
    updated_at?: (string | Date | number);
    name?: string;
    description?: string;
    type?: TAccountingAccountType;
    status?: TAccountingAccountStatus;
    balance?: number;
    currency?: string;
    customer_defined_code?: string;
    is_payable?: boolean;
    parent_id?: string;
    taxonomy?: IAccountingAccountTaxonomy[];
    organization_id?: string;
    metadata?: IAccountingMetadata[];
    raw?: unknown;
}

IAccountingAccountTaxonomy {
    type: 'CLASSIFICATION' | 'GROUP' | 'SUBGROUP' | 'SYSTEM_ROLE' | 'OTHER';
    value: string;          // the provider's value, e.g. "Expense"
    original_type?: string; // the provider's field name, e.g. "AccountType"
}

Each entry in taxonomy is one level of the provider's hierarchy:

• CLASSIFICATION — the top-level class (Asset, Liability, Equity, Revenue, Expense)
• GROUP — the provider's account type
• SUBGROUP — the provider's account subtype
• SYSTEM_ROLE — a system role the provider assigns to the account, where applicable
• OTHER — any other provider-specific level

type is still returned as Unified's normalized account type, so you can filter consistently across providers without reading the taxonomy.

Hierarchy philosophy

Most accounting systems follow a hierarchy like:

Classification → Account Type → Account Subtype

Unified keeps each level as a taxonomy entry, so that:

• No provider-specific fields leak into the model
• Reporting logic stays consistent across integrations
• New providers (and new hierarchy levels) can be added without schema changes
• original_type tells you exactly which provider field each value came from

QuickBooks Online (QBO) → Unified mapping

Creating or updating accounts in QBO: send either type or a taxonomy entry of type GROUP (a valid QBO AccountType). A SUBGROUP entry sets AccountSubType, and a CLASSIFICATION entry sets Classification.

Xero → Unified mapping

Example

A QBO expense account returns:

{
  "id": "123",
  "name": "Office Supplies",
  "type": "EXPENSE",
  "taxonomy": [
    { "type": "CLASSIFICATION", "value": "Expense", "original_type": "Classification" },
    { "type": "GROUP", "value": "Expense", "original_type": "AccountType" },
    { "type": "SUBGROUP", "value": "OfficeGeneralAdministrativeExpenses", "original_type": "AccountSubType" }
  ]
}

Benefits of this design

• Consistent reporting across providers
• No schema changes needed for new accounting platforms
• Provider quirks isolated to mapping logic, not the core model
• Full provider hierarchy preserved, with the source field recorded for each level

Summary

Unified's accounting account hierarchy is generic but expressive. By mapping each provider's structure into taxonomy entries (CLASSIFICATION → GROUP → SUBGROUP, plus SYSTEM_ROLE where available), Unified supports complex accounting use cases without inflating the data model.