Product Vendor Mapping

First-Pass Node Dossier

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

What It Is

ProductVendorMapping is the validated link between a staged vendor catalog item and a canonical product. It stores review state plus price and inventory multipliers, and it is the main control point that turns vendor-side supply into canonical inventory rows.

Parent hierarchy:

• Inventory & Vendor Supply
• Vendor-To-Product Mapping And Review
• Product Vendor Mapping

Primary implementation paths:

• packages/framework/src/Models/ProductVendorMapping.php
• packages/framework/src/Actions/ProductVendorMapping
• packages/framework/src/Exports/ProductVendorMapping/BulkEditor
• packages/framework/src/Imports/ProductVendorMapping/BulkEditor

What Users Can Do With It

Direct capabilities

Admin operators can:

• create a mapping from a vendor catalog item to a canonical product
• edit mapping multipliers and source status
• delete a mapping
• mark a mapping reviewed or unreviewed
• sync canonical inventory from a mapping
• bulk update, review, calculate, sync, or delete mappings through Excel
• review mappings in a dedicated vendor mappings page

Indirect capabilities

Other workflows also create or change mappings:

• accepting a successful mapping attempt creates a mapping with default multipliers
• legacy vendor-item migration can backfill mapping ownership
• staged vendor inventory changes can force projected-multiplier recalculation or resync pressure

Things users cannot do directly

This first pass did not find a generic admin API controller for ProductVendorMapping. The packaged management surface is admin workflow plus Excel tooling, not generic REST CRUD.

Where It Is Managed

Channel	Role	Notes
Vendor > Mappings	Direct	Dedicated packaged mappings page with review state and filters
Vendor catalog-item mapping dialogs	Parent-owned	Direct create and edit dialogs for one catalog item
Excel import/export	Direct	First-class bulk editor workflow
Mapping attempts	Indirect	Accepting an attempt creates a mapping
Storefront	Indirect	Customers only feel the downstream effects

Sources:

Channel-Level Field Coverage

Catalog-item mapping dialogs

The inspected create and edit form exposes:

• product_sku
• inventory_multiplier
• price_multiplier
• is_source

Source:

Dedicated mappings page

The main mappings page is review-oriented. It exposes filtering and row actions around:

• work status
• manufacturer filters
• search
• review state
• projected cost and stock
• sync and delete actions

Sources:

Excel bulk editor

The exported workbook contains:

• product_vendor_mappings
• catalog_items_without_mapping

The main mapping sheet exposes editable action columns around:

• mapping_id
• price_multiplier
• inventory_multiplier
• is_source

and supports import actions:

• delete
• update
• review
• unreview
• calculate
• sync

The unmapped-items sheet is the create path. It expects:

• action=create
• vendor_item_id
• product_manufacturer_code
• product_sku
• optional price_multiplier, inventory_multiplier, and is_source

Workbook behavior that matters operationally:

• the export pre-fills price_multiplier and inventory_multiplier as 1
• the import path also defaults blank multipliers to 1 on the create sheet
• the update sheet requires mapping_id and only requires multipliers when action=update

Sources:

• packages/framework/src/Exports/ProductVendorMapping/BulkEditor/ProductVendorMappingsExport.php
• packages/framework/src/Exports/ProductVendorMapping/BulkEditor/Sheets/ProductVendorMappingsSheet.php
• packages/framework/src/Exports/ProductVendorMapping/BulkEditor/Sheets/CatalogItemsWithoutMappingSheet.php
• packages/framework/src/Imports/ProductVendorMapping/BulkEditor/ProductVendorMappingsImport.php
• packages/framework/src/Imports/ProductVendorMapping/BulkEditor/Sheets/ProductVendorMappingsSheet.php

Model fields that are system-managed

The model also stores operational fields that the create/edit form does not ask the user to type directly:

• product_vendor_catalog_item_id
• product_id
• product_vendor_id
• vendor_item_code
• projected_price_multiplier
• projected_inventory_multiplier
• flagged_for_review_reason
• flagged_for_review_at
• reviewed_at

Source:

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

Configuration And Data Model

Key model characteristics:

• soft-deletable
• generated UUIDs
• review and validity state derived from flags
• projected multipliers calculated from staged vendor and product data
• delete event dispatches cleanup

Important states:

State	Meaning
is_valid	either never flagged or already reviewed
is_invalid	flagged and still unreviewed
is_to_be_reviewed	invalid and awaiting review
status	exposed as valid, reviewed, or invalid

Sources:

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

Relationships

ProductVendorMapping directly relates to:

• product()
• productVendor()
• productVendorCatalogItem()
• productInventoryItems()
• mappingAttempts()
• latestMappingAttempt()

Practical owner:

• the mapping belongs operationally to the staged vendor catalog item, not to the canonical product alone

Sources:

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

Rules And Downstream Effects

Create and update behavior

When a mapping is created:

• product_vendor_id and vendor_item_code are auto-populated from the staged catalog item
• projected multipliers are calculated immediately
• if the mapping is valid and staged vendor inventory exists, canonical inventory sync runs automatically from the model lifecycle

When a mapping is updated:

• multiplier changes recalculate projected multipliers
• valid multiplier changes can mark the mapping reviewed
• valid reviewed changes can resync canonical inventory from the model lifecycle

Sources:

• packages/framework/src/Models/ProductVendorMapping.php
• packages/framework/src/Actions/ProductVendorMapping/UpdateOrCreateProductVendorMapping.php

Source-mapping rule

Only one source mapping is allowed per canonical product. Setting is_source on one mapping clears it from the others for the same product.

Source:

• packages/framework/src/Actions/ProductVendorMapping/UpdateOrCreateProductVendorMapping.php

Delete behavior

Deleting a mapping deletes related canonical inventory rows before soft-deleting the mapping itself.

Sources:

• packages/framework/src/Actions/ProductVendorMapping/DeleteProductVendorMapping.php
• packages/framework/src/Listeners/ProductVendorMapping/DeleteProductVendorMappingRelationships.php

Integrations And Automation

Canonical inventory sync

This node is the main bridge between staged vendor supply and canonical inventory.

Source:

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

Excel

ProductVendorMapping has first-class Excel bulk-management support.

Sources:

• packages/framework/src/Exports/ProductVendorMapping/BulkEditor
• packages/framework/src/Imports/ProductVendorMapping/BulkEditor

Mapping attempts

Successful accepted mapping attempts create mappings with default multipliers.

Source:

• packages/framework/src/Actions/ProductMappingAttempt/AcceptMappingAttempt.php

Where It Appears To End Users

ProductVendorMapping is not a shopper-facing concept.

Its practical effect is indirect:

• canonical inventory appears or changes
• stock levels change
• downstream sellable supply can appear or disappear

Current Documentation Takeaways

1. ProductVendorMapping is the control plane record that turns staged vendor supply into canonical inventory.
2. The packaged product treats it as a first-class workflow even without a generic CRUD API.
3. Multipliers, review state, and source ownership all have automatic downstream effects.

Open Questions

• ProductVendorItem still exists as a legacy model over the product_vendor_mappings table, so some older naming remains under the surface.
• Some row-level mapping UI details live in templates that were not opened in this pass, but the main mapping actions and bulk-tooling contracts were verified.