Product Merchandising Control (PMC)

Appearance

Product Merchandising Control (PMC) ​

PMC — Product Merchandising Control

PMC is the publish-time stamping/control plane that turns PVM product models into channel/facility-specific published product records.

  • Base URL: https://api.g3nretailstack.com/pmc/...
  • OpenAPI: https://doc.g3nretailstack.com/pmc/openapi.yaml
  • Auth (API Gateway):
    • x-orgcode (required)
    • x-session-guid (user session) OR x-api-key (org-bound service account)
  • Roles:
    • Read: pmc_view (owner implied; accepts pvv/viewer and pma/admin synonyms)
    • Write: pmc_publish (owner implied; accepts pma/admin synonyms)
  • Anti-enumeration: non-associated callers may receive 404 not-found (see /common/troubleshooting.html).
  • Role matrix: /common/role-matrix.html
  • Headers and identity cheat sheet: /common/headers-identity.html

Principles ​

  • Immutable revision records per publish.
  • Exactly one online revision (or none) per product identity.
  • Org-gated: all tenant APIs require a valid session/API key and an org association.
  • Client-driven runs: publish orchestration is API-driven but client-executed (/publish/run/*).
  • Auto-offline: when upstream PVM containers become ineligible (status != active), PMC clears online revisions (drift window: minutes).
  • Selector rule: when targeting a single variant, supply both style_id and variant_id (PVM variant lookup is style-scoped).
  • Content packs are immutable, versioned bundles referenced by pack refs (payloads stored in S3).
  • Publish runs emit manifest parts to S3 and expose presigned read URLs via publish/run/manifest/*.
  • Pointer kinds beyond online (staged, preview, fallback) are explicit and revisioned.

Mental model ​

  • Identity: PVM variant × OFM sales channel (sales channel implies logical facility + market/locale).
  • Publish: creates a new immutable revision, records reason, and makes it the online revision (replacing any previously-online revision).
  • Control: operators (with pmc_publish) can switch which revision is online or clear online entirely.

Querying (practical posture) ​

  • Serving queries are exact-match and use curated list filters on GET /product/list (see Surfaces).
  • GET /product/list also supports exact-match “lookup keys” like variant_code, sku, barcode_value, identifier_type+identifier_value, and alias_tag+alias_value (see OpenAPI).
  • PVM resolvers remain useful when you want current PVM truth without republishing, or when a lookup key isn’t indexed in PMC (e.g., GET /pvm/resolve/barcode, GET /pvm/resolve/code).
  • Partial-match search (prefix/contains/regex) is available via GET /product/search and is backed by PMC’s search plane (OpenSearch Serverless). Use field=... when possible to narrow queries and reduce cost.

Clarifications (B6) ​

  • Publish model: new revision per publish; immutable snapshots; online pointer is explicit and singular.
  • Channel + facility + locale: channel declarations in OFM supply channel_code, market_code, and locale_codes; PMC queries require channel context for scoped searches.
  • PVM linkage: publish snapshots PVM data at publish time; PMC queries do not hit PVM, so expect staleness until republish.