Product Vendor Catalog 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

ProductVendorCatalogInventoryItem is the staged vendor stock record for one vendor catalog item at one inventory location, minimum quantity, and optional lot. It is the vendor-side inventory layer that feeds canonical ProductInventoryItem creation and refresh.

Parent hierarchy:

• Inventory & Vendor Supply
• Vendor Supply Master And Feed Staging
• Product Vendor Catalog Inventory Item

Primary implementation paths:

• packages/framework/src/Models/ProductVendorCatalogInventoryItem.php
• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Runs/UpdateOrCreateProductVendorCatalogInventoryItem.php
• packages/framework/src/Actions/ProductVendorCatalogInventoryItem

What Users Can Do With It

Direct capabilities

Admin operators can:

• review staged vendor inventory rows from a vendor catalog-item detail page
• delete a staged vendor inventory row from that detail page
• list staged vendor inventory rows through the admin API

Indirect capabilities

Other workflows use this record to:

• compute canonical inventory through vendor mappings
• determine vendor stock status, pricing changes, and discontinued state
• decide whether canonical inventory should be deleted or resynced when staged rows disappear

Things users cannot do directly

The inspected packaged UI did not expose a direct create or edit form for this node. Creation and mutation are feed-driven.

Where It Is Managed

Channel	Role	Notes
Vendor catalog-item detail page	Direct read-only	Review staged vendor inventory and delete a row
Admin API	Direct read-only	index only
Data feeds	Indirect upstream input	Main create and update path
Vendor reports	Indirect	Several exports and reports read staged vendor inventory
Storefront	Indirect	Only affects shoppers after mapping and canonical sync

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/ProductVendorCatalogInventoryItemsController.php
• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Runs/UpdateOrCreateProductVendorCatalogInventoryItem.php

Creation Model

ProductVendorCatalogInventoryItem is primarily system-generated.

The effective write path is:

1. a data-feed run emits a staged inventory row with sku and location_code
2. UpdateOrCreateProductVendorCatalogInventoryItem resolves the matching vendor location
3. the action upserts the staged row by:
   • catalog item
   • inventory location
   • minimum quantity
   • lot number
4. the model recalculates stock_status on save
5. validated vendor mappings can later translate the staged row into canonical inventory

Sources:

• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Runs/UpdateOrCreateProductVendorCatalogInventoryItem.php
• packages/framework/src/Models/ProductVendorCatalogInventoryItem.php
• packages/framework/src/Actions/ProductVendorMapping/SyncInventoryItems.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• revisionable for cost and MSRP changes
• schemaless extra attributes
• stock-status auto-update on save

Important fields:

Field	Purpose
product_vendor_catalog_item_id	parent staged vendor product
product_inventory_location_id	vendor location supplying the staged stock
minimum_quantity	only 1-quantity rows participate in canonical sync
lot_number	optional lot separation key
available	vendor-side quantity
available_uom_code	vendor quantity unit
cost_unit_price	vendor cost
msrp_unit_price	vendor MSRP
backorder_allowed	vendor backorder behavior
clearance	vendor clearance flag
discontinued	vendor discontinued flag
detected	feed-detection state

Sources:

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

Relationships

Direct relationships:

• productVendorCatalogItem()
• productInventoryLocation()
• dataFeedRun()
• latestDataFeedRun()

Practical dependents:

• canonical inventory sync
• vendor stock and pricing reports
• no-longer-detected cleanup

Sources:

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

Rules And Downstream Effects

Stock and no-longer-detected behavior

• stock_status is updated automatically while saving
• detection and archival scopes determine which staged rows are considered active
• the model tracks recent pricing changes through revision history

After each automated feed run, the Post Import Check step performs no-longer-detected cleanup in order:

1. Catalog items not seen in the last 30 days (excluding manual imports) are marked detected = false.
2. The corresponding staged inventory items for those catalog items are also marked detected = false.
3. Staged inventory items that are no longer detected and still need out-of-stock normalization are updated (available = 0, stock_status = OUT_OF_STOCK, discontinued = true). Only rows that actually require a change are touched; items already fully normalized are skipped.
4. discontinued_at is filled in only when it is null — existing timestamps are preserved.

The cleanup runs as an ordered batch pipeline, processing rows in chunks of 500. This prevents timeouts for large vendor catalogs and makes the step idempotent: re-running it against an already-normalized dataset produces no unnecessary database writes.

Sources:

• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Runs/PostImportCheck.php
• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Runs/PostImportCheck/AddPostImportCheckJobsToBatch.php
• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Runs/PostImportCheck/ProcessPostImportCheckChunk.php

Delete behavior

Deleting a staged vendor inventory row:

• soft-deletes the staged row
• if minimum_quantity == 1, dispatches related canonical-inventory cleanup
• the cleanup either deletes canonical inventory rows or resyncs them from remaining staged rows

Sources:

• packages/framework/src/Actions/ProductVendorCatalogInventoryItem/DeleteProductVendorCatalogInventoryItem.php
• packages/framework/src/Actions/ProductVendorCatalogInventoryItem/DeleteRelatedProductInventoryItem.php

Canonical-sync participation

Only staged rows with minimum_quantity == 1 participate in the main mapping-driven canonical inventory sync.

Source:

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

Integrations And Automation

Data feeds

This node is directly owned by vendor feed import processing.

The enabled feed features decide whether inventory, cost, MSRP, and discontinued fields are updated.

Sources:

• packages/framework/src/Services/DataFeed/Actions/ProductVendor/Runs/UpdateOrCreateProductVendorCatalogInventoryItem.php
• packages/framework/src/Services/DataFeed/Features/ProductVendor/CatalogInventory

Exports and reports

Staged vendor inventory appears in:

• catalog inventory reports
• generic stock-file exports
• recent pricing-change reports
• mapping-multiplier reports

Sources:

• packages/framework/src/Exports/ProductVendor/CatalogInventoryItemsReport.php
• packages/framework/src/Exports/ProductVendor/GenericStockFileExport.php
• packages/framework/src/Exports/ProductVendor/InventoryItemWithRecentPricingChangesReport.php
• packages/framework/src/Exports/ProductVendor/CatalogItemsMappingMultiplierReport.php

Where It Appears To End Users

ProductVendorCatalogInventoryItem is not directly visible to shoppers.

It is an operator and feed-staging record whose effect becomes customer-visible only after vendor mappings translate it into canonical inventory, pricing, and availability.

Current Documentation Takeaways

1. ProductVendorCatalogInventoryItem is staged vendor stock, not canonical sellable stock.
2. It is mostly feed-driven and review-only in the packaged UI.
3. Deleting it can either remove or recalculate canonical inventory, depending on what staged supply remains.

Open Questions

• The inspected base product did not expose a direct edit form for staged vendor inventory, but host applications could still add one.
• This pass did not inspect every reporting blade that renders staged inventory rows, only the main admin surfaces and export classes.