Catalog & PIM

Products are mirrored from Shopify and enriched with a CMS-authored overlay (PIM). The CMS owns multi-language descriptions, custom attributes and metafields, and writes them back to Shopify when needed.

Product mirror

Stored at /content/commerce/products/product_{id}.json. Main properties:

Property	Source
`commerce:product_id` / `commerce:title` / `commerce:handle`	Shopify
`commerce:status`	ingestion status (`received` / `threshold_pending` / `review_pending` / `monitored` / `error` / `deleted`)
`commerce:source_status`	Shopify `active` / `archived` / `draft`
`commerce:vendor` / `commerce:product_type` / `commerce:tags`	Shopify (used in rule matching)
`metafields`	mirror of Shopify metafields (when Admin API enabled)
`pim` / `pim:updated_at`	the CMS PIM overlay

PIM overlay

The pim property holds CMS-authored enrichment.

{
  "attributes": { "material": "cotton" },
  "localized": {
    "ja": { "title": "...", "description_html": "..." },
    "en": { "title": "...", "description_html": "..." }
  },
  "metafields": [ { "namespace": "custom", "key": "care", "type": "single_line_text_field", "value": "..." } ],
  "updatedAt": "...", "updatedBy": "operator@example.com"
}

it lives on the same node as the product, so it shares version history and ACLs
writes deep-merge by default (merge:true); use merge:false to replace

Unified view & search

commerce.Pim.view composes "Shopify base + metafields mirror + PIM overlay". Search uses JCR jcr:contains over the whole product JSON (titles, descriptions, tags, custom attributes).

Endpoints

GET  …/endpoints/pim.groovy?q=keyword[&limit=50]   # full-text search
GET  …/endpoints/pim.groovy?productId=123           # unified view
GET  …/endpoints/pim.groovy?productId=123&raw=true  # overlay only
POST …/endpoints/pim.groovy {productId, pim:{...}, merge:true}  # write

Pushing metafields to Shopify

POST …/endpoints/sync.groovy {action:"metafields", productId:123}

Reads pim.metafields and applies them with the Admin metafieldsSet mutation (requires adminApi.enabled in shopify.yml; records an audit trail).

Operating it

In the Webtop Commerce PIM app, search products and edit localized content, custom attributes and metafields. The Shopify base is shown read-only; saving applies changes while preserving unmanaged keys. With the Admin API enabled, push metafields to Shopify from the toolbar.