Tools

Data health

Five tools make an assistant a catalog auditor: two reads over the cached quality state, one non-destructive scan recompute, and two remediation batches that fix what the scan found — as drafts, never straight to Shopify.

get_data_health_v1

get_data_health_v1pim:read

Read the account's catalog-quality state per dimension — sync, completeness, media, structure, cross-store divergence, translations — as of the last scan. This never scans, so it is cheap.

Argument	Type	Description
`channel_id`	string	Scope to one store.

null means "never scanned", not "clean".

A dimension that has never been scanned comes back null. Call run_data_health_scan_v1 when you need fresh numbers.

list_data_health_issues_v1

list_data_health_issues_v1pim:read

List the individual items behind one section's numbers — which products are unpublished, which are missing required fields, where stores disagree, which files are unused.

Argument	Type	Description
`section`	string, required	Which issue list to read — e.g. `sync-failed`, `completeness-required`, `divergence`, `media-unused`, `translations-untranslated`.
`channel_id`	string	Scope to one store.
`locale`	string	Narrow the translation sections to one target language.
`page`	integer	1-based page number.
`page_size`	integer	Rows per page (clamped to the server max).

run_data_health_scan_v1

run_data_health_scan_v1pim:write

Recompute one dimension and cache the result. The scan reads the catalog and writes only a cached snapshot — it touches no merchant data and nothing reaches Shopify, so it is a non-destructive recompute: re-running it simply recomputes the same dimension.

Argument	Type	Description
`dimension`	string, required	Which dimension to recompute.
`channel_id`	string	Scope the scan to one store, where the dimension is store-scoped.

Scanning the catalog is slow — call it on request rather than polling it. It shares publish's extended 120 s budget, as do the two remediation batches below.

fill_completeness_gaps_v1

fill_completeness_gaps_v1pim:write

Write values into fields that are still empty, in one batch. The server re-checks before every write: a field filled by someone else since the last scan is skipped, never overwritten.

Argument	Type	Description
`entity_type`	string, required	Which kind of item the batch targets — e.g. `Product` or `Variant`.
`operations`	array, required	Up to 500 fills; each names one item, one store, one field, and the value to write.
↳ `master_id`	string, required	The item id.
↳ `channel_id`	string, required	The store id.
↳ `field`	string, required	The field key to fill.
↳ `value`	string, required	The value to write (must not be blank).

reconcile_value_divergence_v1

reconcile_value_divergence_v1pim:write

Bring one field into agreement across stores, in one batch: either adopt a winner store's value or write an explicit one. Stores that already match are left untouched.

Argument	Type	Description
`entity_type`	string, required	Which kind of item the batch targets — e.g. `Product` or `Variant`.
`operations`	array, required	Each names one item and one field, plus exactly one of `winner_channel_id` or `value`.
↳ `master_id`	string, required	The item id.
↳ `field`	string, required	The field key to harmonize.
↳ `winner_channel_id`	string	Adopt this store's value. Mutually exclusive with `value`.
↳ `value`	string	Write this value to every store that differs. Mutually exclusive with `winner_channel_id`.
↳ `channel_id`	string	Narrow an explicit value to one store.

Batch semantics: drafts, and partial success is normal

Drafts only. Both remediation batches write Peak PIM drafts — nothing reaches Shopify. Publish afterwards with publish_master_v1.
Partial success is normal. Read the per-operation results, not just the absence of an error — some operations in a batch can succeed while others are skipped or fail.
Re-checked before write. Fills only land on still-empty fields; reconciliation only touches stores that actually differ. Stale scan data can't cause an overwrite.
Write-annotated. Both batches carry the same destructive-write annotations as the attribute patches, and both are blocked with 423 during import/refresh reconciliation.

The audit-and-fix loop

get_data_health_v1 — where does the catalog stand? (run_data_health_scan_v1 first if a dimension is stale or null.)
list_data_health_issues_v1 — which items, exactly?
fill_completeness_gaps_v1 / reconcile_value_divergence_v1 — fix them as drafts, in batches.
publish_master_v1 — a person or a publish-tier connection pushes the result live.