Variance

Overview

Variances are inventory adjustments that correct stock levels when physical counts don't match system records. They represent the "take" or "add" transactions that reconcile actual inventory with expected inventory, creating stock history entries that adjust quantities and costs to reflect reality.

The most common scenario is cycle counting. Workers count products in a specific location or sublocation. The count reveals a discrepancy - the system shows 100 units but the physical count finds only 95. A variance transaction adjusts the system down by 5 units, creating a stock history entry for the shortage. This keeps inventory accurate without waiting for full annual physical inventories.

Variances can both remove stock (when physical counts are lower than system records) and add stock (when physical counts are higher). The transaction records the quantity adjusted, the cost impact, and the reason for the adjustment. This creates an audit trail explaining why inventory changed outside of normal shipment and build transactions.

Cost adjustments are another use case. If you discover that inventory is valued at an incorrect cost - perhaps a data entry error during receiving - a variance can adjust the average cost to the correct value. This ensures your inventory valuation and cost of goods sold calculations are accurate, supporting correct financial reporting.

Variances typically require explanation. The description field captures why the adjustment was needed - cycle count discrepancy, damage, theft, data entry correction, or other reasons. This documentation supports loss prevention analysis, process improvement, and audit review. Patterns in variance reasons might reveal operational issues that need addressing.

The system tracks who created each variance and when. This accountability helps prevent fraudulent adjustments and supports investigation when variances are questioned. Variance approval workflows in some organizations require management review before large adjustments are processed, adding an additional control layer.

From an accounting perspective, variances affect both inventory quantities and values. They create general ledger entries that adjust inventory asset accounts and typically expense accounts for losses or revenue accounts for gains. These GL impacts ensure the financial records reflect the physical reality of what's actually in the warehouse.

GraphQL API

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

Query Name: varianceViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
11 filter options
5 sortable fields
8 relations to other collections

Query Examples

Basic Query

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

query {
  varianceViewConnection(first: 10) {
    edges {
      node {
        cancelTransactionTimestamp
        cbm
        commitTransactionTimestamp
        cost
        lotId
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

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

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

Filtering

Apply filters to narrow results (see Filters section for all available options):

query {
  varianceViewConnection(
    first: 10
    connectionRelationErrorDates: { begin: "2024-01-01", end: "2024-12-31" }
  ) {
    edges {
      node { lotId }
    }
  }
}

Sorting

Sort results by one or more fields:

query {
  varianceViewConnection(
    first: 10
    sort: [{ field: "note", mode: "desc" }]
  ) {
    edges {
      node {
        lotId
        note
      }
    }
  }
}

Relations

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

query {
  varianceViewConnection(first: 10) {
    edges {
      node {
        lotId
        cancelTransactionUser {
          name
          userLoginUrl
        }
      }
    }
  }
}

Summary and Aggregation

This collection supports metrics aggregation through the summary field. You can calculate totals, averages, counts, and other aggregate values across filtered data.

Note: This collection does not support groupBy dimensions. For dimensional analysis, use collections like product, order, or invoice.

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

Query Structure

varianceViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 2 metrics that can be aggregated:

Metric	Parameters	Description
`totalValuation`	`transform`, `operator`	totalValuation for variance
`count`	None	Count of items in the result set

Common Parameters:

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

Examples

Example 1: Total variance Metrics

Calculate aggregate metrics across all variance records:

query {
  varianceViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      metrics {
        totalCount: count
      }
    }
  }
}

Expected result structure:

{
  "data": {
    "varianceViewConnection": {
      "summary": {
        "errorCode": null,
        "errorMessage": null,
        "metrics": {
          "totalCount": [1523]
        }
      }
    }
  }
}

Fields

This collection has 30 fields:

28 simple fields
2 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.

`cancelTransactionTimestamp`

The date and time when the variance record was cancelled. This field is populated when a variance transaction moves to cancelled status, recording when the stock adjustment was invalidated or reversed. This timestamp appears alongside the commit transaction timestamp and cancel transaction user fields, tracking the cancellation event for audit purposes.

Label: Cancel transaction timestamp
Sortable: No

`cbm`

The total volume measurement for the variance record, expressed in cubic meters (CBM). This field captures the volumetric quantity associated with the inventory variance transaction and is displayed as a CBM subtotal in reporting contexts.

Label: CBM subtotal
Sortable: No

`commitTransactionTimestamp`

The timestamp indicating when the variance transaction was committed to the system. This represents the point in time when the variance was finalized and officially recorded, as opposed to when it might have been canceled or created in draft form.

Label: Commit transaction timestamp
Sortable: No

`cost`

The total standard accounting cost for the variance transaction, calculated by multiplying the variance quantity by the product's standard accounting cost per unit. This represents the value of the inventory adjustment at standard cost for accounting purposes. This field requires authorization to view cost information.

Label: Std accounting cost amount
Sortable: No

`lotId`

The lot identifier that specifies which batch or lot of inventory is being counted or adjusted in the variance transaction. This field allows tracking inventory variances at the lot level, which is essential for businesses that manage lot-tracked products with expiration dates, manufacturing dates, or batch numbers. When users perform a physical inventory count, they can specify the lot ID to record quantity discrepancies for specific lots of a product, rather than just adjusting overall quantities. The lot ID can be left empty for products that are not lot-tracked.

Label: Lot ID
Sortable: No

`lotIdUnprefixed`

Label: Lot ID unprefixed
Sortable: No

`nativeNeq`

Label: Native NEQ subtotal
Sortable: No

`nativeWeight`

The total weight of the items in this variance record, expressed in the product's native weight unit of measure. This subtotal provides a summary of the aggregate weight across all items or line items included in the variance, displayed in reports and listings for inventory reconciliation purposes.

Label: Native Weight subtotal
Sortable: No

`neq`

The net explosive quantity (NEQ) for the variance, representing the total amount of net explosive mass for the product quantity involved in this inventory variance transaction. This value is calculated by multiplying the variance quantity by the product's net explosive mass per unit, and is formatted and displayed according to the product's system of measure for explosive content.

Label: NEQ subtotal
Sortable: No

`note`

A text field for recording general comments or notes about the variance record. This field allows users to add explanatory information about the stock change, such as the reason for the adjustment or other contextual details relevant to the variance transaction.

Label: Note
Sortable: Yes

`packing`

The case packaging configuration for the product in this inventory variance item, indicating how units are packaged in cases. This field specifies the packing format such as "12 cs 12/1" (12 cases with 12 units per case) and is used when recording inventory adjustments or physical counts for case quantities rather than open stock. When a variance item includes packing information, it indicates the adjustment applies to full cases of product rather than individual units.

Label: Packing
Sortable: No

`quantity`

The amount by which inventory quantities changed for a product in a variance transaction. This represents the difference between the counted quantity and the system's recorded quantity on hand. Positive values indicate inventory gains (more stock found than expected), while negative values indicate inventory losses or shrinkage (less stock found than expected). For stock takes and adjustments, this field captures the net change in quantity that results from the variance.

Label: Quantity
Sortable: No

`quantityCaseOrCaseEquivalent`

Label: Quantity, case or case equivalent
Sortable: No

`quantityCaseStock`

Label: Quantity, case stock
Sortable: No

`quantityOpenStock`

Label: Quantity, open stock
Sortable: No

`reason`

The reason code explaining why the inventory variance occurred. Each variance can have items with different reason codes (such as Lost, Found, Damaged, Spoiled, or Integration), and when a variance contains multiple items with different reasons, the variance-level reason field displays "Multiple reasons". Reason codes can be configured as active or inactive for different variance types, specifically stock takes versus stock changes, allowing businesses to control which reason codes are available for different types of inventory adjustments.

Label: Reason
Sortable: No

`shortCode`

A user-defined abbreviated identifier that can be used to quickly reference a specific product, packing, and lot combination. This short code serves as a convenient alternative to using the full product name or SKU when recording inventory variances, making data entry faster and more efficient. The short code is looked up from the scan lookup system based on the variance item's product, packing configuration, and lot number.

Label: Short code
Sortable: No

`statusExtended`

An extended status description that provides additional detail about the variance record's current state beyond the basic status. While the status field shows the primary workflow state (Editable, Committed, or Canceled), the statusExtended field offers supplementary status information that may include timing, processing details, or other contextual status indicators relevant to the variance transaction.

Label: Status extended
Sortable: No

`title`

Label: Title
Sortable: No

`totalChangeValue`

The total monetary value of inventory changes recorded in the variance. This represents the financial impact of the quantity adjustments being made, typically calculated by multiplying the variance quantity by the product cost. This field is displayed alongside total count value and total valuation to provide different views of the variance's financial significance.

Label: Total change value
Sortable: No

`totalCountValue`

The total monetary value calculated from inventory counts recorded during the variance process. This field displays as a right-aligned numeric value in variance reports and represents the cumulative value of items counted, helping businesses track the total worth of inventory adjustments.

Label: Total count value
Sortable: No

`totalValuation`

The total monetary value of the inventory variance, calculated by multiplying the quantity variance by the unit cost of the product. This represents the financial impact of the stock discrepancy found during physical inventory counts. For example, if a physical count reveals 5 extra units of a product that costs $10 each, the total valuation would be $50. This field can be summed across multiple variance records to determine the aggregate value of inventory adjustments within a given time period or facility.

Label: Total valuation
Sortable: No

`units`

Label: Units
Sortable: No

`unitsPerCase`

Label: Units per case
Sortable: No

`varianceDate`

The date when the inventory variance or physical inventory count occurred. This field is used to filter and organize variance records by the date the discrepancy was identified or the count was performed. In external integrations like Amazon, Shopify, and other e-commerce platforms, this date is set based on the sync operation timestamp and helps track when inventory adjustments were made in the system.

Label: Date
Sortable: Yes

`varianceId`

The unique identifier for the variance record. This ID is extracted from the variance URL and serves as the primary reference number for the inventory variance transaction. For example, a variance with URL '/ivs/103' would have a varianceId of '103'.

Label: Variance ID
Sortable: Yes
Default Formatter: html

Example Query:

{
  variance(varianceUrl: "example-url") {
    varianceId    # Uses default formatter: html
    varianceIdRaw: varianceId(formatter: "none")  # Get raw value
  }
}

`varianceUrl`

The unique identifier for an inventory variance record. This field is automatically generated by the server and serves as the primary key to reference a specific variance transaction, such as when querying variance details or linking variances to orders and facilities.

IMPORTANT: Treat URL values as opaque strings supplied by the server. Do not attempt to parse, interpret, or construct URL values manually:

ID values embedded in URLs may differ from entity ID values
The URL structure is an internal implementation detail subject to change
Manually constructing URLs can lead to bugs and system errors
Always use URL values exactly as provided by the API

Label: Variance Url
Sortable: No

`weight`

The total weight of the inventory variance, calculated based on the product's weight per unit and the variance quantity. This field provides the aggregate weight impact of the variance transaction, typically expressed in the system's standard unit of measure for weight. It appears alongside native weight to show weight calculations in different measurement systems.

Label: Weight subtotal
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

`status`

The current state of the variance record in the workflow. Possible values include Committed (variance has been finalized and inventory adjustments applied), Editable (variance is still in draft mode and can be modified), and Canceled (variance has been voided and will not affect inventory). This field determines whether the variance can still be edited or whether its inventory changes have been permanently recorded.

Label: Status
Sortable: No

Possible Values:

PHSCL_INV_INPUT - Editable
PHSCL_INV_COMMITTED - Committed
PHSCL_INV_CANCELLED - Canceled

`type`

The category of inventory variance transaction being recorded. This field indicates the nature of the stock adjustment, with values such as "Stock change" representing adjustments made to inventory counts. The type helps users understand what kind of variance activity occurred and how it affects inventory levels.

Label: Type
Sortable: No

Possible Values:

FACILITY - Stock change
SINGLE - Quick stock change
FACILITY_COUNT - Stock take