# 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.

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

### Pagination

Use cursor-based pagination to retrieve large datasets:

```graphql
# 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:

```graphql
query {
  stockViewConnection(
    first: 10
    facilityUrl: "/finaleengineer/api/facility/100000"
  ) {
    edges {
      node { lotId }
    }
  }
}
```

### Relations

Query related data:

```graphql
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.

### Query Structure

```graphql
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:

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

Expected result structure:

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

## Fields

This collection has 13 fields:

- 6 simple fields
- 1 enum field (with predefined values)
- 6 parameterized fields (accept query options)

### Simple Fields

#### `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. This field returns a human-readable string suitable for display in reports and user interfaces.

**Label:** Lot ID

**Sortable:** No

#### `lotIdUnprefixed`

The lot ID formatted without the display prefix. This field strips the descriptive label from the lot ID value, returning only the raw numeric or text portion suitable for data processing.

**Label:** Lot ID unprefixed

**Sortable:** No

#### `packing`

The packaging configuration for a stock item, such as case size or individual unit.

**Label:** Packing

**Sortable:** No

#### `quantity`

The amount of product in a stock transaction or inventory item.

**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

### Enum Fields

#### `type`

The classification of the stock transaction, indicating whether it represents inventory on hand, on order, reserved back-ordered, or reserved on hand.

**Label:** Type

**Sortable:** No

**Possible Values:**

- `STOCK_ITEM_ON_HAND` 
- `STOCK_ITEM_PACKED` 
- `STOCK_ITEM_IN_TRANSIT` 
- `STOCK_ITEM_WIP` 
- `STOCK_ITEM_ON_ORDER` 
- `STOCK_ITEM_RSVD`

### Parameterized Fields

#### `stock`

Represents inventory items and their transactions, including on-hand quantities, reserved quantities, and back-ordered amounts.

**Label:** Stock

**Sortable:** No

**Parameters:**

- **count** (`ProductStockCount`)

Count quantity by

**Options:**
  - `openQuantity` 
  - `caseQuantity` 
  - `totalUnits` 
  - `caseUnits` 
  - `totalCaseEquivalents` 
  - `openCaseEquivalents`
- **facilityUrlList** (`List|FacilityUrlLocationOrSublocation`)

Location(s) or sublocation(s)

- **stockType** (`ProductStockType`)

Type

**Options:**
  - `available`
  - `onHand`
  - `onOrder`
  - `remaining`
  - `reserved`
  - `reservedBackordered`
  - `reservedOnHand`

#### `stockAvailable`

The quantity of product currently available for sale or use, calculated as on-hand inventory minus any reservations.

**Label:** Available to promise

**Sortable:** No

**Parameters:**
- **count** (`ProductStockCount`)

#### `stockOnHand`

The physical quantity of product currently present at a location.

**Label:** Quantity on hand

**Sortable:** No

**Parameters:**
- **count** (`ProductStockCount`)

#### `stockOnOrder`

The quantity of product that has been ordered from suppliers but not yet received.

**Label:** On order

**Sortable:** No

**Parameters:**
- **count** (`ProductStockCount`)

#### `stockRemaining`

The quantity of stock available for allocation, calculated as stock on hand minus reserved stock.

**Label:** Remaining after reservations

**Sortable:** No

**Parameters:**
- **count** (`ProductStockCount`)

#### `stockReserved`

The quantity of product units that have been reserved for customer orders or other commitments.

**Label:** Reservations

**Sortable:** No

**Parameters:**
- **count** (`ProductStockCount`)

## Relations
### build
- **Related Collection:** [build](https://developer.finaleinventory.com/reference/graphql-build)
- **Label:** Build

### location
- **Related Collection:** [facility](https://developer.finaleinventory.com/reference/graphql-facility)
- **Label:** Location

### order
- **Related Collection:** [order](https://developer.finaleinventory.com/reference/graphql-order)
- **Label:** Order

### product
- **Related Collection:** [product](https://developer.finaleinventory.com/reference/graphql-product)
- **Label:** Product

### shipment
- **Related Collection:** [shipment](https://developer.finaleinventory.com/reference/graphql-shipment)
- **Label:** Shipment

### sublocation
- **Related Collection:** [facility](https://developer.finaleinventory.com/reference/graphql-facility)
- **Label:** Sublocation

### sublocationOrLocation
- **Related Collection:** [facility](https://developer.finaleinventory.com/reference/graphql-facility)
- **Label:** Sublocation or location

## Filters
### facilityUrl
- **Label:** Facility
- **Type:** List|FacilityUrlLocationOrSublocationString
- **Enabled:** Yes

### location
- **Label:** Location
- **Type:** List|FacilityUrlLocationString
- **Enabled:** Yes

### lotIdSearch
- **Label:** Lot ID
- **Type:** LotIdSearchString
- **Enabled:** Yes

### orderType
- **Label:** Order type
- **Type:** List|OrderTypeString
- **Enabled:** Yes

### sublocation
- **Label:** Sublocation
- **Type:** List|FacilityUrlSublocationString
- **Enabled:** Yes

### type
- **Label:** Type
- **Type:** List|StockTypeString
- **Enabled:** Yes