Invoice Item

Overview

Invoice Items are the line items on invoices and bills. Invoices contain different types of line items that work together to determine the total amount due. While the invoice represents the overall financial document, invoice items provide the line-by-line detail that supports general ledger posting.

Invoices contain several types of line items. Product items (above-the-line entries) specify a product, quantity, and unit price. These represent the goods or services being charged. For sales invoices created from shipments, product items often reference the specific shipment items they're billing for, linking the physical and financial transactions. This linkage ensures you're billing for exactly what shipped.

Pricing on product items can differ from order pricing. While orders specify list prices, invoices capture actual charged prices that might reflect discounts, promotions, or price adjustments. Product items show both the unit price and the line total. This transparency supports customer inquiries and financial analysis.

Invoices also include adjustment line items (such as discounts or fees) and tax line items. These are separate types of entries that apply to the overall invoice total, not to individual product items. Each product item can be marked as taxable or non-taxable. Taxable product items accumulate into the invoice's taxable subtotal, which is then used to calculate tax amounts that appear as separate tax line items. The system tracks both the taxable subtotal and the calculated tax amounts, supporting tax compliance and reporting.

Cost allocation on sales invoice items supports sophisticated cost accounting. When products are shipped, they leave inventory at their average cost (cost of goods sold). But additional costs like freight, insurance, or import duties might be invoiced later and need to be allocated back to the products. Invoice items track both the revenue side (what the customer pays) and allocated cost side (total cost including allocations), enabling accurate gross margin calculation.

Invoice items for bills (supplier invoices) work similarly but from the purchase perspective. They specify what you're being charged by the supplier, at what unit costs, with what quantities. Matching these bill items to purchase order items and purchase shipment items helps verify you're being charged correctly for what you ordered and received.

The relationship between invoice items and general ledger entries is important for financial accuracy. When an invoice is posted, each invoice item might create or contribute to GL entries. Sales invoice items create revenue entries by product line or category. Allocated costs create cost of goods sold entries. These item-level details aggregate into the GL while preserving drill-down capability for analysis.

GraphQL API

The invoiceItem collection provides access to invoiceItem data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

Query Name: invoiceItemViewConnection

Available Features:

• Cursor-based pagination (first/last/after/before)
• 3 relations to other collections

Query Examples

Basic Query

The invoiceItem collection is accessed via the invoiceItemViewConnection query, which returns a Relay-style connection with pagination support.

query {
  invoiceItemViewConnection(first: 10) {
    edges {
      node {
        allocatedAdjustments
        allocatedMiscellaneous
        allocationBy
        cbm
        class
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

# First page
query {
  invoiceItemViewConnection(first: 50) {
    edges {
      node { productAdjustmentId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  invoiceItemViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { productAdjustmentId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Relations

Query related data (see Relations section for all available relations):

query {
  invoiceItemViewConnection(first: 10) {
    edges {
      node {
        productAdjustmentId
        creditAccount {
          name
          glAccountUrl
        }
      }
    }
  }
}

Summary and Aggregation

This collection supports data aggregation and dimensional analysis through the summary field. You can calculate metrics (like totals, averages, counts) and group them by dimensions (like category, date, status).

For a comprehensive guide to using aggregations, see the Aggregation Concept Guide.

Query Structure

invoiceItemViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    groupBy {
      # Group by dimensions (see table below)
    }
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 27 metrics that can be aggregated:

Common Parameters:

• operator - Aggregation function: sum, mean, min, max
• transform - Mathematical transformation: abs
• dateRange - Filter to specific date range
• facilityUrlList - Filter to specific facilities

GroupBy Dimensions

Group metrics by these dimensions:

All dimensions accept a formatter parameter: "html", "none", "abbreviated", "blank-zero".

Examples

Example 1: Basic Aggregation

Calculate metrics for invoiceItem:

query {
  invoiceItemViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      groupBy {
        # Add dimensions here
      }
      metrics {
        totalCount: count
      }
    }
  }
}

Fields

This collection has 36 fields:

• 33 simple fields
• 3 enum fields (with predefined values)
• 0 parameterized fields (accept query options)

Note on Field Formatting: All scalar fields support the formatter argument to control output format. Available options: "html", "none", "abbreviated", "blank-zero". Some fields have a default formatter (shown below). See the Formatting guide for details.

Note on Sorting: Field sortability may vary depending on the UI context and query parameters used. Some parameter options explicitly disable sorting (marked with ⚠️ not sortable).

Simple Fields

These fields return values directly without additional options.

allocatedAdjustments

The portion of invoice-level adjustments (such as promotions or discounts) that has been allocated or distributed to this specific product line item for profit analysis purposes. While adjustment line items (discounts and fees) are separate entries that apply to the overall invoice total, this field distributes those adjustments proportionally to product items to enable accurate margin calculations. The allocated adjustments are subtracted from the transaction cost to determine the actual cost per unit and are added to the unit price times quantity calculation to determine income after adjustments. This field is particularly relevant for product items on sales invoices where invoice-level promotional adjustments need to be allocated across products for profit analysis, even though the adjustments themselves appear as separate line items on the invoice.

Label: Allocated adjustments
Sortable: No

allocatedMiscellaneous

The portion of miscellaneous charges or fees that has been allocated to this specific invoice line item. This calculated field shows how order-level or invoice-level miscellaneous adjustments are distributed across individual line items based on the allocation method specified in the allocationBy field, such as by subtotal, weight, quantity, or equal distribution. This allocation allows businesses to see the full cost impact of miscellaneous charges on each product or service line on the invoice.

Label: Allocated miscellaneous
Sortable: No

cbm

The total volume in cubic meters (CBM) for the invoice line item, calculated by multiplying the item quantity by the product's volume per unit. This field is used to track the total cubic space occupied by the products on this invoice line, which is important for logistics, freight cost calculations, and container capacity planning.

Label: CBM subtotal
Sortable: No

class

The accounting class assigned to this invoice item, used for financial reporting and categorization. This field can be configured to automatically populate based on various criteria such as the sale source (where the order originated), product category, or custom picklist fields defined on the order. Accounting classes help businesses segment and track revenue or expenses by different business dimensions for more detailed financial analysis and reporting.

Label: Class
Sortable: No

cogs

The estimated cost of goods sold for this invoice line item. This is calculated by multiplying the number of units by the average cost per unit from the associated order. The COGS value represents the estimated expense incurred to acquire or produce the products being invoiced, and is used together with the income amount to calculate profit margins. This field only applies to sales invoices with product items.

Label: COGS (estimated)
Sortable: No

cogsPerUnit

The estimated cost of goods sold per unit for the item on this invoice line. This represents the approximate per-unit cost incurred to acquire or produce the goods being invoiced, which is used to calculate profit margins and track the direct costs associated with each sale.

Label: COGS per unit (estimated)
Sortable: No

cost

Further information is not available.

Label: Std accounting cost amount
Sortable: No

creditAccount

The general ledger account that receives the credit entry for this invoice item. This links each line item on an invoice to the appropriate accounting category for revenue, liabilities, or other credit transactions, enabling proper financial reporting and integration with accounting systems.

Label: Credit account
Sortable: No

debitAccount

The general ledger account that will be debited when this invoice line item is posted to accounting. This field allows users to specify which account should receive the debit entry for the transaction represented by this invoice item, enabling proper double-entry bookkeeping and financial reporting.

Label: Debit account
Sortable: No

descriptionItemNote

A combined field that displays both the item description and any additional notes associated with the invoice line item. This field provides a consolidated view of the product or service description along with any supplementary information or special notes that apply to that specific line item on the invoice.

Label: Description / item note
Sortable: No

discount

The discount percentage applied to the invoice line item, calculated as the difference between the unit list price and the actual unit price. This field is displayed as a percentage and represents how much the item was discounted from its list price. For example, if an item has a list price of $50 and is sold for $40, the discount would be 20%. When users edit this field, it automatically adjusts the unit price accordingly to reflect the new discount percentage.

Label: Discount
Sortable: No

discountFee

A promotional adjustment or discount applied to an invoice item, selected from a list of available product promotions. Users can choose a promotion to apply discounts or fees to line items, with the adjustment amount and description automatically populated based on the selected promotion's rules. This field appears in the user interface as "Adjustment" and allows for both percentage-based and fixed-amount promotions to be applied to invoice items.

Label: Adjustment
Sortable: No

incomeAfterAdjustments

The total revenue for a product line item after applying any promotional adjustments or discounts. For sales invoices, this represents the item's subtotal (unit price multiplied by quantity) plus any allocated promotional adjustments. This field is used in margin calculations to determine profitability by comparing income after adjustments against the cost of goods sold. For purchase invoices, adjustment-related items, and tax items, this field returns null as it only applies to product items on sales invoices.

Label: Income after adjustments
Sortable: No

itemIndex

The sequential line number for each item on an invoice, starting from 1. This field provides the ordering of items as they appear on the invoice, including product items, adjustments, promotions, and tax lines. When importing or displaying invoice data in spreadsheets or reports, the item index determines the position of each line item. The field is automatically assigned based on the item's position in the invoice item list.

Label: Item index
Sortable: No

itemNote

A text field for capturing additional descriptive information about a specific line item on an invoice. This field is commonly used to store product variant details, special instructions, or other notes that provide context beyond the basic product description. For example, when an invoice item represents a product with multiple options like "BB730 Creatine Infused Gummies - Hawaiian Fruit Punch / 1 Pack", the itemNote field would contain this full descriptive text including the variant and quantity information.

Label: Item note
Sortable: No

marginPercentage

The estimated profit margin on the invoice item, expressed as a percentage. This represents the difference between the selling price per unit and the average cost per unit, divided by the selling price. For example, if an item sells for $100 and costs $70 on average, the margin percentage would be 30%. This field helps businesses understand profitability at the line item level and is labeled as estimated because it uses average cost rather than the specific cost of units sold.

Label: Margin percentage (estimated)
Sortable: No

nativeNeq

The net equivalent quantity (NEQ) calculated in the item's native units of measure. This represents the standardized quantity measurement for the invoice line item, displayed as a right-aligned numeric subtotal. The native NEQ reflects the quantity in the product's primary or base unit of measure, as opposed to any converted or alternative units.

Label: Native NEQ subtotal
Sortable: No

nativeWeight

Further information is not available.

Label: Native Weight subtotal
Sortable: No

neq

The Net Explosive Quantity (NEQ) for the invoice item, representing the total amount of explosive content for the line item. This is calculated based on the product's NEQ per unit multiplied by the quantity ordered. NEQ is a critical safety and regulatory metric used in industries dealing with explosives, ammunition, and hazardous materials, helping organizations track and report explosive quantities for compliance and logistics purposes.

Label: NEQ subtotal
Sortable: No

packing

The case packing configuration for products sold or purchased in cases rather than individual units. This field specifies how many units are packed per case using a normalized format like "24 cs 24/1" (indicating 24 cases with 24 units per case) or "12 cs 12/1" (12 cases with 12 units per case). When populated, this indicates the item was invoiced using case quantities instead of open stock, which affects unit calculations, pricing per unit, and inventory tracking. The packing information can override the product's default packing for this specific invoice line item.

Label: Packing
Sortable: No

pricePerUnit

The price charged for a single unit of the product or item on the invoice line. This value is used to calculate the total line item amount when multiplied by the quantity. For items with different packing configurations, the price per unit represents the cost for the base unit rather than per case or other package size. This field is also used in margin percentage calculations to determine profitability by comparing the price per unit against the average cost per unit.

Label: Price per unit
Sortable: No

productAdjustmentId

The identifier of the product or adjustment associated with this invoice line item. This field distinguishes whether the line item represents a regular product charge or an adjustment (such as a discount, fee, or other modification) applied to the invoice. The field enables tracking and reporting on both standard product sales and various adjustments that affect the invoice total.

Label: Product / adjustment ID
Sortable: No

quantity

The number of units of the product being invoiced on this line item. This represents how many of the product (in the unit of measure specified) is included in the invoice. For product items, this is typically a positive number indicating units sold or purchased. Note lines or descriptive items may have a quantity of 0. The quantity is used along with the unit price to calculate the line item total.

Label: Quantity
Sortable: No

quantityCaseOrCaseEquivalent

The quantity of items expressed in cases or case equivalents. This field converts the quantity to a standardized case-based unit of measure, allowing for consistent reporting and analysis across products with different packing configurations. For products sold in cases, this represents the number of cases. For products sold in individual units, this converts the quantity to an equivalent number of cases based on the product's packing size.

Label: Quantity, case or case equivalent
Sortable: No

quantityCaseStock

The quantity of product measured in full cases only, excluding any open stock or partial case quantities. This field appears on invoice items alongside other quantity representations like quantity in units, quantity in case equivalents, and quantity in open stock. It provides a standardized way to view and report on invoice line items specifically in terms of complete case units, which is useful for businesses that track inventory and sales separately by case stock versus open stock (individual units or partial cases).

Label: Quantity, case stock
Sortable: No

quantityOpenStock

The quantity of product on an invoice line item counted as open stock, meaning individual units that are not in sealed cases. This field is used when tracking inventory in both case stock (sealed cases) and open stock (loose units) separately. Open stock represents units that have been removed from cases or are being handled individually rather than as complete cases.

Label: Quantity, open stock
Sortable: No

shortCode

A system-generated barcode identifier that uniquely represents a specific product, packing configuration, and lot combination. This code allows users to quickly scan and identify inventory items on invoices. The short code is automatically assigned by Finale when products are configured with specific packing variations or lot tracking, and appears as a numeric string that can be used for barcode scanning during receiving, picking, or inventory operations.

Label: Short code
Sortable: No

subtotal

The line item total calculated before adjustments are applied. For product line items, this is the quantity multiplied by the unit price. For non-product line items such as adjustments or fees, this is the amount value itself.

Label: Subtotal
Sortable: No

tax

A reference to the specific tax authority rate applied to this invoice item. This field identifies which tax rate configuration is being used for sales tax line items, linking to a tax authority rate product record that defines the tax jurisdiction and rate percentage. For example, it might reference a "CA" state tax or "San Mateo 7.0%" local tax. This field is only populated for invoice items with type INV_SALES_TAX and allows the system to track which specific tax rates were applied when calculating the total tax on the invoice.

Label: Tax
Sortable: No

unitPrice

The price charged per unit for a product on an invoice line item. This represents the actual selling price that the customer is billed, which may differ from the list price if discounts or special pricing has been applied. The unit price is multiplied by the quantity to calculate the line item subtotal. For example, if a product has a unit price of 11.23 and a quantity of 9, the line item total would be 101.07.

Label: Unit price
Sortable: No

units

The total number of individual units for the invoice line item, calculated by multiplying the case quantity by the units per case from the product's packing configuration. For example, if an invoice item has a quantity of 2 cases and the product is packed 12 units per case, this field would show 24 units.

Label: Units
Sortable: No

unitsPerCase

The number of individual units contained within a case for the product on this invoice line item. This field is used when products are sold or invoiced by the case rather than individually, and helps convert between case quantities and individual unit quantities for pricing and inventory calculations. For example, if a product is sold as a case of 12 bottles, the unitsPerCase would be 12.

Label: Units per case
Sortable: No

weight

The total weight for the line item, calculated by multiplying the product's weight per unit by the quantity ordered on this invoice item. This field represents the cumulative weight contribution of this line item to the overall invoice, useful for shipping calculations and weight-based reporting. The weight is displayed in the system's standard unit of measure for weight.

Label: Weight subtotal
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

allocationBy

The method used to allocate or distribute amounts across invoice items. Users can choose from four allocation methods: Subtotal (distributing proportionally based on line item subtotals), Weight (distributing based on item weights), Quantity in units (distributing based on item quantities), or Equal distribution (splitting the amount evenly across all items). This field determines how charges like freight, handling fees, or other miscellaneous costs are apportioned among the items on an invoice.

Label: Allocation by
Sortable: No

Possible Values:

• ADJ_BY_SUBTOTAL - Subtotal
• ADJ_BY_WEIGHT - Weight
• ADJ_BY_UNITS - Quantity in units
• ADJ_BY_EQ_DISTR - Equal distribution

itemType

The category of line item that appears on an invoice, which determines how the item is processed and displayed. Common types include product items (INV_PROD_ITEM) which represent goods or services sold, promotional adjustments (INV_PROMOTION_ADJ) which represent discounts or other pricing adjustments, and sales tax items (INV_SALES_TAX) which represent tax charges. This field allows invoices to contain a mix of different item types, enabling proper separation of products, adjustments, taxes, and other charges for accurate financial reporting and invoice presentation.

Label: Item type
Sortable: No

Possible Values:

• INV_PROD_ITEM - Product
• INV_PROMOTION_ADJ - Discount / fee / external tax
• INV_SALES_TAX - Sale / VAT tax

taxHandling

Indicates how the invoice item should be handled for tax calculation purposes. The field determines whether a discount or fee is taxable (meaning taxes apply to it), nontaxable (exempt from taxes), or if the item itself represents a tax charge. This allows the system to properly calculate total tax amounts on invoices by identifying which line items should be included in or excluded from the taxable amount, and which items are tax charges themselves rather than goods or services being taxed.

Label: Tax handling
Sortable: No

Possible Values:

• null - Taxable discount / fee
• NON_TAXABLE - Nontaxable discount / fee
• EXT_TAX - Tax

Relations

creditAccount

• Related Collection: generalLedgerAccount
• Label: Credit account

TODO: Add relation description

debitAccount

• Related Collection: generalLedgerAccount
• Label: Debit account

TODO: Add relation description

product

• Related Collection: product
• Label: Product

TODO: Add relation description

Filters

No filters available.