Products

What it is

Product master data — one row per variant (per size/version, not per model). Combines shop-synced facts (SKU, name, price, stock, active flag) with procurement master data you maintain in the app: supplier assignment, purchase price, MOQ, lead times, safety/target stock days, seasonality profile, and lifecycle status. Variants of the same model are grouped by product_family (source product gid) with a human-readable product_family_label derived from the title. The procurement views — Product Demand, Procurement Queue, Family Trend — are all computed on top of this table.

How it gets data

Ingest-enabled — shop syncs push rows through the Ingest API; the procurement columns are edited in the app (or via MCP data_row_update) and survive re-syncs:

POST /api/ingest/products
Authorization: Bearer pk_...
Content-Type: application/json

One JSON record per request; unknown fields are dropped.
Upsert identity is the variant, not the SKU: products upsert on (tenant_id, identity_key) where identity_key = COALESCE(external_id, sku). Send the source variant id as external_id (Shopify ProductVariant gid) — several sizes of one model can share a SKU, and without external_id they would overwrite each other. Integrations that only have a SKU may omit external_id; then the SKU is the identity.
tenant_id / workspace_id come from the API key context, never from the body.
A ready-made Make.com flow template is downloadable in Settings → Data Sources.

Minimal example payload:

{
  "external_id": "gid://shopify/ProductVariant/445566",
  "sku": "6304",
  "name": "Claire 6304 — 16 cm",
  "price": 249.90,
  "currency": "EUR",
  "stock": 12,
  "active": true,
  "product_family": "gid://shopify/Product/778899"
}

Fields

Identity & shop facts

Field	Label	Type	Writable	Description
`external_id`	Variant ID	text	ingest	Stable source variant id (Shopify ProductVariant gid). The preferred identity; when NULL the upsert identity falls back to the SKU
`identity_key`	—	text	API only	Generated upsert arbiter: `COALESCE(external_id, sku)`. Unique per tenant; system-maintained, never writable
`sku`	SKU	text	ingest	Article/model number. Deliberately not the identity — several sizes of one model can share a SKU
`name`	Name	text	ingest	Variant title. Required
`product_family`	Shopify Product ID	text	✓	Source model/product group (Shopify Product gid). All sizes of a model share it. Not a key — manually correctable; NULL rows are treated as their own group by the procurement views
`product_family_label`	Product Family	text	trigger	Human-readable model family, derived from the product title (rule: `procurement_config.family_rule`). Set by a database trigger on every write
`price`	Price	currency	ingest	Selling price
`currency`	Currency	text	ingest	Selling currency
`stock`	Stock	number	ingest	Stock on hand from the shop sync — the number all coverage calculations start from
`active`	Active	boolean	ingest	Whether the variant is active/sellable in the shop
`inventory_synced_at`	Last Sync	datetime	ingest	When stock was last synced — feeds the data-freshness gates in the procurement queue
`metadata`	—	json	API only	Raw source fields that don’t map to a column

Procurement master data (maintained in the app)

Field	Label	Type	Writable	Description
`procurement_trackable`	Track	boolean	✓	Include this variant in procurement planning. Untracked variants never appear in the queue
`lifecycle_status`	Lifecycle	status	✓	`launch` / `growth` / `stable` / `declining` / `discontinued`. Scales planned demand via a lifecycle factor and gates recommendations for discontinued items
`supplier_id`	Supplier	text	✓	Assigned supplier — joins to `suppliers.id`; the variant inherits the supplier’s default lead time / target stock when its own are empty
`supplier_sku`	Supplier SKU	text	✓	Article number at the supplier, printed on order lists
`purchase_price`	Purchase Price	currency	✓	Buying price per unit
`purchase_currency`	Purchase Currency	text	✓	Buying currency
`minimum_order_quantity`	Min. Order	number	✓	Supplier MOQ — recommendations are rounded up to it
`order_multiple`	Order Multiple	number	✓	Order quantities are rounded to this multiple (e.g. carton size)
`lead_time_days`	Lead Time (d)	number	✓	Variant-specific lead time; overrides the supplier default
`lead_time_buffer_days`	Lead Buffer (d)	number	✓	Extra buffer on top of the lead time for customs/quality delays
`safety_stock_days`	Safety Stock (d)	number	✓	Days of demand held as safety stock — part of the replenishment risk window
`target_stock_days`	Target Stock (d)	number	✓	Target coverage in days an order should restore
`seasonality_profile`	Seasonality	status	✓	Which seasonality profile applies — see Seasonality
`is_advertised`	Advertised	boolean	✓	Currently being advertised — context for interpreting demand spikes
`manual_demand_multiplier`	Demand Multiplier	number	✓	Manual factor multiplied into planned demand (e.g. 1.5 before a campaign)
`manual_target_quantity`	Manual Target Qty	number	✓	Manual forecast for variants without sales history (`demand_status = MANUAL_FORECAST`)
`procurement_paused_until`	Paused Until	date	✓	Exclude the variant from recommendations until this date
`procurement_note`	Procurement Note	text	✓	Free-text note for the buyer/agent, shown alongside recommendations

“ingest” = populated through the ingest endpoint; read-only in the app. ✓ = editable in the app and settable on create; edits survive shop re-syncs. “API only” = real database column not registered as a visible app column. “trigger” = computed by the database on write.

Like every workspace table, products also carry the system columns id, tenant_id, workspace_id, created_at, and updated_at — set automatically, never sent by integrations.

Query it

{
  "method": "tools/call",
  "params": {
    "name": "data_query",
    "arguments": {
      "view_slug": "products",
      "filters": { "procurement_trackable": true, "active": true },
      "select_fields": ["sku", "name", "stock", "lead_time_days", "supplier_sku"],
      "sort_by": "stock",
      "sort_desc": false,
      "limit": 50
    }
  }
}

AI Operating Guide

Vertical Intelligence

Getting Started

Governance

Resources

Sales & Commerce

Procurement

Marketing & Outreach

What it is

How it gets data

Fields

Identity & shop facts

Procurement master data (maintained in the app)

Query it

​What it is

​How it gets data

​Fields

​Identity & shop facts

​Procurement master data (maintained in the app)

​Query it

What it is

How it gets data

Fields

Identity & shop facts

Procurement master data (maintained in the app)

Query it