Stock

Overview

Stock represents your current inventory levels - how much of each product you have right now, where it's located, and what its status is. Unlike most collections which are stored in the database, stock levels are calculated in real-time by summing up all the stock history transactions. This means stock is always accurate and reflects every inventory movement that has occurred.

Stock exists in different states based on where it is in your operational processes. On-hand stock is physically in your warehouse and available for use. Packed stock has been assigned to a specific shipment and is reserved, still physically present but not available for other orders. In-transit stock is moving between your facilities after being shipped from one location but before being received at the destination. Work-in-progress (WIP) stock represents components that have been consumed by a manufacturing build but haven't yet been completed into finished goods.

Reserved stock shows what's allocated to committed sales orders. When you commit a sales order, the required inventory is reserved, preventing it from being promised to other customers even though it's still on hand. Available stock is the key metric for new orders - it's your on-hand quantity minus what's already reserved. This available quantity tells you what you can actually promise to new customers right now.

Stock aggregates across different dimensions to give you the views you need. You can see total stock for a product across all locations, or drill down to see stock in a specific warehouse or even a specific bin within that warehouse. For lot-tracked products, you can view stock by lot ID, seeing separate quantities for each lot with different expiration dates or cost bases.

The GraphQL API provides multiple ways to query stock. You can query by product to see where a specific item is located and how much you have. You can query by location to see all products stored in a particular warehouse. You can filter by stock type to see only packed items or only in-transit items. This flexibility supports different operational needs from order fulfillment to warehouse management to financial reporting.

Stock quantities can be expressed in different units depending on your product's packing configuration. For a product packed "12/1" (12 units per case), you might want to see quantities as total units (144), case equivalents (12.0 cases), or separate open quantity (8 units) and case quantity (11 cases). The API supports these different views, letting you work with quantities in the most natural format for your operations.

GraphQL API

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

Query Name: stockViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
6 filter options
7 relations to other collections

Query Examples

Basic Query

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

query {
  stockViewConnection(first: 10) {
    edges {
      node {
        averageCost
        lotId
        lotIdUnprefixed
        packing
        quantity
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

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

# Subsequent pages
query {
  stockViewConnection(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 {
  stockViewConnection(
    first: 10
    facilityUrl: "/finaleengineer/api/facility/100000"
  ) {
    edges {
      node { lotId }
    }
  }
}

Relations

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

query {
  stockViewConnection(first: 10) {
    edges {
      node {
        lotId
        build {
          buildId
          buildUrl
        }
      }
    }
  }
}

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

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

Available Metrics

This collection provides 1 metric that can be aggregated:

Metric	Parameters	Description
`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 stock Metrics

Calculate aggregate metrics across all stock records:

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

Expected result structure:

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

Fields

This collection has 13 fields:

6 simple fields
1 enum fields (with predefined values)
6 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.

`averageCost`

The average cost per unit for this specific stock item at the time it was recorded. This value represents the weighted average cost calculation for the product associated with this stock record, considering the specific lot, packing, and facility combination. The average cost is used for inventory valuation and cost of goods sold calculations throughout the system.

Label: Average cost
Sortable: No

`lotId`

The lot ID associated with this stock item, formatted with a descriptive prefix such as "Lot: ", "Mfg: " (manufacturing date), or "Exp: " (expiration date). This field returns a human-readable string suitable for display in reports and user interfaces. Query using lotId(formatter: "default") to get the formatted value with the appropriate prefix based on the lot ID type.

Label: Lot ID
Sortable: No

`lotIdUnprefixed`

The lot ID formatted without the display prefix (e.g., "Lot: ", "Mfg: ", or "Exp: "). This field strips the descriptive label from the lot ID value, returning only the raw numeric or text portion suitable for data processing or form population. Query using lotIdUnprefixed(formatter: "none") to get the unformatted value.

Label: Lot ID unprefixed
Sortable: No

`packing`

The packaging configuration for a stock item, such as case size or individual unit. This determines whether stock quantities represent full cases or individual units when counting inventory.

Label: Packing
Sortable: No

`quantity`

The amount of product in a stock transaction or inventory item. Depending on the packing configuration, this represents either the number of cases or the number of individual units.

Label: Quantity
Sortable: No

`title`

A descriptive name or label for the stock item, typically derived from the product name or other identifying information.

Label: Title
Sortable: No
Default Formatter: html

Example Query:

{
  stock(stockUrl: "example-url") {
    title    # Uses default formatter: html
    titleRaw: title(formatter: "none")  # Get raw value
  }
}

Enum Fields

These fields return one of a predefined set of values.

`type`

The classification of the stock transaction, indicating whether it represents inventory on hand, on order, reserved back-ordered, or reserved on hand. This type determines how the stock quantity is calculated and reported in availability metrics.

Label: Type
Sortable: No

Possible Values:

STOCK_ITEM_ON_HAND - On hand
STOCK_ITEM_PACKED - Packed
STOCK_ITEM_IN_TRANSIT - In transit
STOCK_ITEM_WIP - WIP
STOCK_ITEM_ON_ORDER - On order
STOCK_ITEM_RSVD - Reserved

Parameterized Fields

These fields accept parameters to customize the returned data. Parameters allow filtering by location, date ranges, aggregation methods, and more.

`stock`

Represents inventory items and their transactions, including on-hand quantities, reserved quantities, and back-ordered amounts. This is the core collection for tracking product availability across facilities.

Label: Stock
Sortable: No

Parameters:

count (ProductStockCount) - Default: totalUnits Count quantity by

Options:
- openQuantity - Open stock
- caseQuantity - Case stock
- totalUnits - Units including open and case stock
- caseUnits - Units including case stock only
- totalCaseEquivalents - Case equivalents including open and case stock
- openCaseEquivalents - Case equivalents including open stock only
facilityUrlList (List|FacilityUrlLocationOrSublocation) Location(s) or sublocation(s)
stockType (ProductStockType) Type

Options:
- available - Available
- onHand - On hand
- onOrder - On order
- remaining - Remaining after reservations
- reserved - Reserved
- reservedBackordered - Reserved backordered
- reservedOnHand - Reserved on hand

Example Query:

{
  stock(stockUrl: "example-url") {
    stock(
      count: totalUnits
      facilityUrlList: ["example-value"]
      stockType: available
    )
  }
}

`stockAvailable`

The quantity of product currently available for sale or use, calculated as on-hand inventory minus any reservations. This represents the unreserved stock that can be allocated to new orders.

Label: Available to promise
Sortable: No

Parameters:

count (ProductStockCount) - Default: totalUnits Count quantity by

Options:
- openQuantity - Open stock
- caseQuantity - Case stock
- totalUnits - Units including open and case stock
- caseUnits - Units including case stock only
- totalCaseEquivalents - Case equivalents including open and case stock
- openCaseEquivalents - Case equivalents including open stock only
facilityUrlList (List|FacilityUrlLocation) Location(s)

Example Query:

{
  stock(stockUrl: "example-url") {
    stockAvailable(
      count: totalUnits
      facilityUrlList: ["example-value"]
    )
  }
}

`stockOnHand`

The physical quantity of product currently present at a location. This is the total inventory count including both available and reserved units, representing what is actually in the facility.

Label: Quantity on hand
Sortable: No

Parameters:

count (ProductStockCount) - Default: totalUnits Count quantity by

Options:
- openQuantity - Open stock
- caseQuantity - Case stock
- totalUnits - Units including open and case stock
- caseUnits - Units including case stock only
- totalCaseEquivalents - Case equivalents including open and case stock
- openCaseEquivalents - Case equivalents including open stock only
facilityUrlList (List|FacilityUrlLocationOrSublocation) Location(s) or sublocation(s)

Example Query:

{
  stock(stockUrl: "example-url") {
    stockOnHand(
      count: totalUnits
      facilityUrlList: ["example-value"]
    )
  }
}

`stockOnOrder`

The quantity of product that has been ordered from suppliers but not yet received. This represents incoming inventory that will increase stock levels once purchase orders are fulfilled.

Label: On order
Sortable: No

Parameters:

count (ProductStockCount) - Default: totalUnits Count quantity by

Options:
- openQuantity - Open stock
- caseQuantity - Case stock
- totalUnits - Units including open and case stock
- caseUnits - Units including case stock only
- totalCaseEquivalents - Case equivalents including open and case stock
- openCaseEquivalents - Case equivalents including open stock only
facilityUrlList (List|FacilityUrlLocation) Location(s)

Example Query:

{
  stock(stockUrl: "example-url") {
    stockOnOrder(
      count: totalUnits
      facilityUrlList: ["example-value"]
    )
  }
}

`stockRemaining`

The quantity of stock available for allocation, calculated as stock on hand minus reserved stock. This field supports optional parameters including count (units, case equivalents), facilityUrlList for filtering by specific facilities, formatter for output formatting, and timezone for timestamp-based calculations.

Label: Remaining after reservations
Sortable: No

Parameters:

count (ProductStockCount) - Default: totalUnits Count quantity by

Options:
- openQuantity - Open stock
- caseQuantity - Case stock
- totalUnits - Units including open and case stock
- caseUnits - Units including case stock only
- totalCaseEquivalents - Case equivalents including open and case stock
- openCaseEquivalents - Case equivalents including open stock only
facilityUrlList (List|FacilityUrlLocation) Location(s)

Example Query:

{
  stock(stockUrl: "example-url") {
    stockRemaining(
      count: totalUnits
      facilityUrlList: ["example-value"]
    )
  }
}

`stockReserved`

The quantity of product units that have been reserved for customer orders or other commitments. Reservations can include units already on hand or units on order that are allocated to specific customers.

Label: Reservations
Sortable: No

Parameters:

count (ProductStockCount) - Default: totalUnits Count quantity by

Options:
- openQuantity - Open stock
- caseQuantity - Case stock
- totalUnits - Units including open and case stock
- caseUnits - Units including case stock only
- totalCaseEquivalents - Case equivalents including open and case stock
- openCaseEquivalents - Case equivalents including open stock only
facilityUrlList (List|FacilityUrlLocation) Location(s)
reservationType (ProductStockReservationType) - Default: backOrdered Reservation type

Options:
- all - Backordered + on hand
- backOrdered - Backordered
- onHand - On hand

Example Query:

{
  stock(stockUrl: "example-url") {
    stockReserved(
      count: totalUnits
      facilityUrlList: ["example-value"]
      reservationType: backOrdered
    )
  }
}