Product Inventory Item

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

ProductInventoryItem is the canonical sellable inventory row in Pyle. It ties one product to one inventory location and stores the current quantity, cost, MSRP, and fulfillment-relevant stock state that downstream pricing, cart, and fulfillment flows consume.

Parent hierarchy:

• Inventory & Vendor Supply
• Inventory Network And Canonical Availability
• Product Inventory Item

Primary implementation paths:

• packages/framework/src/Models/ProductInventoryItem.php
• packages/framework/src/Actions/ProductInventoryItem
• packages/framework/src/Http/Controllers/Api/Admin/ProductInventoryItemsController.php
• packages/framework/src/Http/Controllers/Api/Admin/InventoryItemsController.php

What Users Can Do With It

Direct capabilities

Admin operators can:

• review canonical inventory rows in the packaged inventory screen
• review a product's per-location availability and stock history in the availability dialog
• list, create, update, and delete inventory rows through the product-scoped admin API
• query all canonical inventory rows through the global read-only admin inventory API

Indirect capabilities

Other workflows change ProductInventoryItem without treating it as the primary object:

• accepting or editing vendor mappings can create or recalculate canonical inventory
• ERP sync can upsert canonical inventory rows
• inventory-location deactivation or mapping deletion can remove related rows

Things users cannot do directly

In the inspected packaged admin UI, users do not get a dedicated create or edit dialog for canonical inventory rows.

Where It Is Managed

Channel	Role	Notes
Admin inventory page	Direct read-only	The packaged page lists canonical inventory rows but does not expose a dedicated inspected edit dialog
Product availability dialog	Parent-owned	Product detail workflows show per-location rows and stock-history review
Admin API (products/{product}/inventory_items)	Direct	Full list, create, show, update, destroy for a product
Admin API (inventory_items)	Direct read-only	Global read-only query surface with product and location filters
Storefront resources	Indirect	Nested in product-offer, cart, and order flows rather than a standalone page
ERP, vendor mappings, data feeds	Indirect upstream input	These are major write paths into canonical inventory

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/ProductInventoryItemsController.php
• packages/framework/src/Http/Controllers/Api/Admin/InventoryItemsController.php
• packages/framework/src/Actions/ProductInventoryItem/SyncInventoryItem.php
• packages/framework/src/Actions/ErpBridge/ProductInventoryItem/UpdateOrCreateModelFromDTO.php

Channel-Level Field Coverage

Packaged admin inventory surfaces

The inspected packaged UI is review-oriented.

The global inventory table exposes:

• product
• brand
• category
• available quantity
• stock status

The product availability dialog exposes row data such as:

• warehouse or location name
• location city
• vendor name
• vendor code
• available quantity
• MSRP
• last updated timestamp

It also opens stock-history review for the selected row.

Sources:

Vendor catalog-item review surfaces

When operators inspect a staged vendor catalog item, the packaged detail view also shows the resulting canonical inventory rows with fields such as:

• inventory location
• mapped product
• available quantity
• cost
• MSRP
• discontinued flag
• backorder flag
• timestamps

Source:

Product-scoped admin API

The product-scoped API supports direct create and update using these validated fields:

• product_inventory_location_id
• product_vendor_item_id
• available
• cost
• backorder_allowed
• external_id

The list endpoint allows query shaping for:

• id
• product_id
• product_inventory_location_id
• product_vendor_item_id
• available
• cost
• country_code_of_origin

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/ProductInventoryItemsController.php
• packages/framework/src/Actions/ProductInventoryItem/CreateProductInventoryItem.php
• packages/framework/src/Actions/ProductInventoryItem/UpdateProductInventoryItem.php

Important contract note:

• backorder_allowed is required in both create and update validation even though the packaged admin UI does not expose a dedicated canonical-inventory form

Global admin inventory API

The global inventory_items endpoint is read-only and adds product-oriented filters such as:

• product.sku
• product.product_manufacturer_id
• product.product_category_id
• product.product_type_id
• productOffers.id
• stock and availability scopes

It can include:

• product
• product.productManufacturer
• productVendorItem
• productVendorItem.productVendor
• productInventoryLocation
• productInventoryLocation.productVendor
• priceHistories

Source:

• packages/framework/src/Http/Controllers/Api/Admin/InventoryItemsController.php

Model fields that exist but are not exposed in the inspected packaged UI

The model also carries fields that the inspected UI does not directly author:

• product_vendor_mapping_id
• msrp
• discontinued
• clearance
• processing_delay_days
• country_code_of_origin

Source:

• packages/framework/src/Models/ProductInventoryItem.php

Storefront field filtering

The storefront resource removes internal cost fields:

• cost
• cost_decimal
• cost_presentable

It keeps the inventory row and nests a storefront inventory-location resource.

Source:

• packages/framework/src/Http/Resources/Storefront/ProductInventoryItemResource.php

Configuration And Data Model

Key model characteristics:

• ERP-syncable
• soft-deletable
• geographical through the related inventory location
• price-history aware
• stock-history aware

Important fields:

Field	Purpose
product_id	canonical product being sold
product_inventory_location_id	warehouse or pickup location supplying the stock
available	canonical available quantity
cost	canonical cost in integer money format
msrp	canonical MSRP in integer money format
backorder_allowed	affects computed stock status
discontinued	contributes to downstream product stock behavior
clearance	marks clearance state propagated from vendor supply
product_vendor_mapping_id	current validated mapping that sourced the row

Behavioral notes:

• stock_status is computed from available and backorder_allowed
• productOffersPriceRange derives pricing snapshots from related public offers
• location-distance scopes use the related inventory-location geography

Legacy note:

• product_vendor_item_id still exists and is used in some sync and delete paths even though the main current ownership pointer is product_vendor_mapping_id

Sources:

• packages/framework/src/Models/ProductInventoryItem.php
• packages/framework/src/Actions/ProductInventoryItem/SyncInventoryItem.php

Relationships

ProductInventoryItem directly relates to:

• product()
• productOffers()
• productInventoryLocation()
• productVendorItem()
• productVendorMapping()

Trait-based supporting relationships:

• priceHistories()
• stockHistories()
• latestPriceHistory()
• latestStockHistory()

Practical owners and dependents:

• vendor mappings can create or refresh it
• products depend on it for stock recalculation
• storefront offer and cart flows consume it indirectly

Sources:

• packages/framework/src/Models/ProductInventoryItem.php
• packages/framework/src/Models/Traits/PriceHistoriesTrait.php
• packages/framework/src/Models/Traits/StockHistoriesTrait.php

Rules And Downstream Effects

Observer-driven side effects

When a canonical inventory row changes:

• changing cost logs a price-history row
• changing available logs a stock-history row
• creating a row queues product stock recalculation
• changing available, backorder_allowed, or discontinued queues product stock recalculation

Sources:

• packages/framework/src/Observers/ProductInventoryItemObserver.php
• packages/framework/src/Actions/StockHistory/LogStockHistory.php

Important history caveat:

• creation paths do not seed an initial history row
• history is only written on updates when the relevant value actually changes
• "price history" here is cost history, not MSRP history

Sources:

• packages/framework/src/Actions/PriceHistory/LogPriceHistory.php
• packages/framework/src/Actions/StockHistory/LogStockHistory.php

Mapping-driven sync

SyncInventoryItem creates or updates canonical inventory from a valid ProductVendorMapping plus staged vendor inventory.

Important rules in that path:

• rows with minimum_quantity > 1 are skipped
• only active inventory locations are considered
• vendor cost, MSRP, and quantity are multiplied by mapping multipliers
• discontinued, clearance, and backorder state are aggregated from staged vendor inventory

Sources:

• packages/framework/src/Actions/ProductVendorMapping/SyncInventoryItems.php
• packages/framework/src/Actions/ProductInventoryItem/SyncInventoryItem.php

Delete and deactivation effects

• deleting a mapping deletes related canonical inventory rows
• deactivating an inventory location dispatches cleanup for related inventory
• deprecation cleanup can delete rows that no longer resolve to a vendor item, inventory location, or raw vendor inventory support record

Sources:

• packages/framework/src/Actions/ProductVendorMapping/DeleteProductVendorMapping.php
• packages/framework/src/Actions/ProductInventoryLocation/UpdateProductInventoryLocation.php
• packages/framework/src/Actions/ProductInventoryItem/InspectProductInventoryItemForDeprecation.php

Integrations And Automation

ERP bridge

Canonical inventory is a direct ERP sync object.

Sources:

• packages/framework/src/Services/ErpBridge/ProductInventoryItem/ProductInventoryItemErpSyncService.php
• packages/framework/src/Actions/ErpBridge/ProductInventoryItem/UpdateOrCreateModelFromDTO.php
• packages/erp-bridge/src/Requests/ProductInventoryItems/GetProductInventoryItemsRequest.php

Vendor feeds and mapping automation

Vendor feed staging does not write ProductInventoryItem directly. It writes staged vendor records, then validated mappings sync into canonical inventory.

Sources:

• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Runs/UpdateOrCreateProductVendorCatalogInventoryItem.php
• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Importers/InventoryItems/ProcessInventoryItemsChunk.php
• packages/framework/src/Actions/ProductVendorMapping/SyncInventoryItems.php

Excel

This pass did not find a dedicated packaged Excel import or export for canonical ProductInventoryItem rows themselves.

Where It Appears To End Users

ProductInventoryItem is not a first-class shopper concept.

It appears indirectly through:

• product-offer payloads
• cart and order-item payloads
• storefront stock and availability behavior

What shoppers effectively experience is:

• whether the product is available
• whether backorder is possible
• which location-backed shipping or pickup paths remain eligible

The storefront inventory payload still includes row-level availability and the nested storefront inventory-location resource, but it strips internal cost presentation fields.

Sources:

• packages/framework/src/Http/Resources/Storefront/ProductInventoryItemResource.php
• packages/framework/src/Http/Resources/Storefront/ProductOfferResource.php
• packages/framework/src/Http/Resources/Storefront/CartItemResource.php
• packages/framework/src/Http/Resources/Storefront/OrderItemResource.php

Current Documentation Takeaways

1. ProductInventoryItem is the canonical inventory record, not the raw vendor feed row.
2. The packaged admin mostly exposes it as a review surface, while mappings and ERP sync are the heavy write paths.
3. Inventory updates can create both history rows and delayed product stock recalculation.

Open Questions

• product_vendor_item_id still behaves like a legacy field in some sync paths, and should not be treated as a clean modern ownership pointer without deeper migration review.
• The inspected packaged admin UI exposes review flows, but no dedicated create or edit dialog for canonical inventory rows was found.