PVM - Product and Vendor Management

PVM is the product modeling system. It captures how a retailer or brand describes suppliers, product taxonomy, styles, variants, codes, and related metadata. If you want a definitive record of what a product is and how it is structured, PVM is the source of truth.

PVM is designed to support real merchandising workflows. It has clear lifecycle rules, strong validation, and explicit relationships between suppliers, brands, and product records.

Service scope and boundaries

PVM owns the product model and supplier relationships. It does not publish products (PMC does that) and it does not manage organizations or sessions (OFM/USM do that). Its job is to maintain a consistent, validated catalog of products and related metadata.

Implemented feature breakdown (what exists today)

Supplier layer

• Vendor and manufacturer records with lifecycle status.
• Role-based control for supplier mutations.

Brand management

• Brand records with lifecycle status.
• Brand-to-supplier links, including primary relationships.

Taxonomy

• Division, department, category, and season entities.
• Category hierarchy validation and status management.

Product modeling

• OGM (product model group) with create, clone, list, get, status.
• Styles with create, list, get, update, status, and OGM reassignment.
• Variants with create, list, get, status, and staleness operations.
• Option groups and options with matrix-based combinations.

Identifiers and lookup

• Identifiers, aliases, and barcodes as first-class objects.
• Add, list, status, and resolve flows.
• Code resolution and uniqueness enforcement.

Collaboration and relationships

• Comments with attachments.
• Comment reporting for large attachments.
• Kit components, alternatives, and supplementary links.

History and maintenance

• Status history reporting.
• Variant update for inactive records.
• Template defaults with propagation across OGM, style, and variant.

How the features are implemented (behavioral breakdown)

Suppliers and brands

• Vendors and manufacturers are created and managed with lifecycle statuses.
• Brands are created separately, then linked to suppliers.
• Styles that reference a brand must respect brand-to-supplier link coverage.

Taxonomy

• Divisions and departments form the top of the hierarchy.
• Categories must fit within a department and follow depth and hierarchy rules.
• Seasons provide an additional planning dimension for releases.

OGM, styles, and variants

• OGM records define shared product model context.
• Styles group sets of variants and reference suppliers and taxonomy categories.
• Variants represent sellable options derived from a style and option matrix.
• Variants can be marked stale and recreated to keep model integrity.

Options and matrices

• Option groups and options define allowed combinations (for example, size and color).
• Matrices enforce valid combinations and protect against invalid variant creation.

Identifiers, aliases, and barcodes

• Identifiers and aliases are used for cross-system lookup.
• Barcodes are used for scan and retail workflows.
• Active records enforce uniqueness to prevent collisions.
• Resolve surfaces allow lookup of products by code or barcode.

Comments and attachments

• Comments attach to product-related records for collaboration.
• Attachments are handled with presigned upload flows.
• Comment records follow lifecycle status rules.
• Comment reporting surfaces help identify unusually large attachments.

Kits, alternatives, and links

• Kits allow modeling of bundle components.
• Alternatives provide substitution paths.
• Supplementary links connect related items without embedding data directly.

Template defaults

• Template defaults define baseline econ, tax, compliance, and dimension data.
• Defaults propagate from OGM to style and variant unless overridden.

Compliance extensions (as-built)

• Regional compliance warnings: per-market labels and warnings via compliance.labels_by_market.
• Recall/stop-sale controls: compliance.recall and compliance.stop_sale with scoped markets/channels/regions.
• Restricted distribution: compliance.restricted_distribution for channel/region allow/deny lists.
• Delivery constraints: compliance.delivery_constraints for signature-required, age-verified delivery, carrier restrictions.
• Allergens and ingredients: compliance.allergens + compliance.ingredients for ingredient panels, allergen flags, and sensitive tags.

Policy metadata (as-built)

PVM now stores operational constraints directly in product records and propagates them across OGM → Style → Variant.

• Packaging and storage requirements: packaging_requirements captures pack/case/pallet metadata, materials, fragility/stack limits, orientation, and storage constraints (temperature, humidity, light sensitivity, cold-chain) with handling notes.
• Commercial policy constraints: commercial_policy includes returnability, return windows, non-returnable reasons, restocking fee percent, RTV eligibility/windows, never-on-sale flag, minimum sale price (MAP/price floor), and below-cost allowance (percent + approval requirement). Facility overrides are supported via commercial_policy.facility_overrides keyed by logical facility GUID.
• Warranty and service policy: remains planned (warranty length, serviceability, parts availability, repair eligibility).

Example use cases (extensive)

Supplier onboarding: A brand onboards new vendors and manufacturers, verifies them, and links them to existing brand records. Product teams can now reference those suppliers in styles.

Taxonomy build-out: Merchandising defines divisions, departments, and categories for a new line. Categories are validated for hierarchy and status, ensuring consistent classification before styles are created.

Style and variant creation: A style is created with valid suppliers and taxonomy. Option groups define size and color, and variants are generated based on the option matrix. Each variant receives identifiers and barcodes for downstream use.

Data correction with audit trail: A product manager corrects a style record, updates variant data, and records the change with a comment and attachment. Concurrency control ensures edits do not overwrite concurrent changes.

Variant updates for inactive products: A product that is not live is updated through the inactive-only update flow, ensuring safe edits without touching active inventory.

Barcode and identifier management: A retailer adds barcodes and aliases for a set of variants, then uses resolve endpoints to map external system codes back to internal products.

Bundle modeling: A fulfillment team models a kit (bundle) and defines alternative items for substitution. This keeps product options explicit and supports operational workflows without hiding relationships in unstructured notes.

Comment abuse monitoring: An operator reviews the comment report to find unusually large attachments and decide whether to clean up or request changes.

Seasonal refresh: A new season is created, and styles are updated to reflect the new collection. Variants are recreated where option matrices changed.

Regional compliance and returns: A product carries a CA Prop 65 warning and is non-returnable in certain facilities with a restocking fee override elsewhere. Downstream systems enforce the policy at checkout and returns. Recall and distribution controls: A regulated item is stop-sale in specific regions and barred from marketplace channels. Downstream systems block sale and enforce delivery restrictions.

Constraints and invariants

• PVM is org-scoped and role-based. Only authorized members or service accounts can create or modify records.
• Some edits require the record to be inactive to protect live product data.
• Styles must reference valid suppliers and a valid taxonomy category.
• Brand usage must be covered by brand-to-supplier links when a style references a brand.
• Barcodes and identifiers must be unique across active records.
• Some status transitions are blocked if dependent records still exist.
• Revisioned records require explicit concurrency control to prevent overwrites.
• Policy constraints are authoritative in PVM; downstream services enforce them using org defaults and facility overrides.

How PVM fits with other services

OFM provides the organization and membership model used for authorization. USM provides sessions and API keys that allow PVM access. PMC consumes PVM snapshots to publish channel-specific products, but PVM itself does not publish products. SCM and PPM enforce PVM policy constraints (returns, sale eligibility, price floors), and PCM uses PVM data for vendor return eligibility and packaging requirements.

Implemented vs planned

Implemented: supplier and brand management, taxonomy, OGM/styles/variants, option matrices, identifiers and barcodes, comments and attachments, kits, alternatives, supplementary links, history status, inactive-only variant updates, template defaults with propagation, compliance extensions, and policy metadata for packaging/storage + commercial constraints.

Planned: warranty/service policy metadata (warranty length, serviceability, parts availability, repair eligibility). Publishing is handled by PMC rather than PVM.

For exact request and response shapes, see the PVM contract pages at https://doc.g3nretailstack.com/pvm/.