Tools

Collection sources

The per-store definitions that decide which products a collection holds. Reads: each store's complete definition, a membership preview from saved or proposed criteria, and copy compatibility. Writes (write): add a source, edit its criteria and selections, copy it to a store, replace a store's definition, copy a definition to every eligible store. Source removal is deliberately not offered. Changes ship with the collection's next publish.

get_collection_sources_v1

get_collection_sources_v1pim:read

Read every store's complete source definition for one collection: each source's kind and title, its conditions (criteria), hand-picked inclusions, exclusions (named products, excluded collections, value rules), sub-collections, and the entities it references — as Shopify holds them (GIDs) in `definition`, and as PIM items with the source's own projection_id (the address the edit/copy tools take), whether it awaits publish, and whether the store's definition is editable or stale, in `editing`. A store the PIM has not read sources for is absent.

Argument	Type	Description
`id`	string, required	The item id (must belong to the token's account; cross-account ids return not found).

preview_collection_products_v1

preview_collection_products_v1pim:read

Estimate which products a collection would hold on one store from its SAVED sources, or from PROPOSED criteria: each source_override replaces one saved source (source_projection_id) or appends a provisional one (no id, then source_type is required). Evaluated against the PIM's current drafts; anything the estimator cannot restate (app-owned or locked sources, excluded collections, inventory rules) falls back to the store's live membership, so the answer is always marked estimated. Read-only.

Argument	Type	Description
`channel_id`	string, required	The store id.
`id`	string, required	The collection id.
`source_overrides`	array of object	Proposed criteria (at most 100).

Extended timeout. 120 s per call — the operation runs server-side orchestration or a live Shopify read.
Live Shopify read. Slower than PIM reads and can fail when Shopify is unavailable.

get_collection_source_copy_preflight_v1

get_collection_source_copy_preflight_v1pim:read

Inspect copy compatibility before copying: with source_projection_id, one source's target stores (the source's own store first — the duplicate-in-place offer — then every other store carrying the collection); with collection_id + source_channel_id, the whole store definition's targets. Each target reports whether it is blocked (and why) and the referenced items it lacks, which a copy would silently drop.

Argument	Type	Description
`collection_id`	string	The collection, for a whole-definition check.
`source_channel_id`	string	The store whose definition would be copied (with collection_id).
`source_projection_id`	string	One source (from get_collection_sources_v1's editing map).

create_collection_source_v1

create_collection_source_v1pim:write

Stage a new source on one store's collection: a PRODUCTS or VARIANTS source selects by conditions and/or hand-picked products (at least one of the two), a COLLECTIONS source draws from sub-collections (collection_master_ids only). Exclusions remove named products, whole collections, or products matching value rules. Referenced items are PIM ids and must already be published on that store. The source ships with the collection's next publish_master_v1.

Argument	Type	Description
`channel_id`	string, required	The store id.
`collection_id`	string, required	The collection id.
`collection_master_ids`	array of string	For a COLLECTIONS source: the sub-collections, by PIM id.
`conditions`	array of object	The rule conditions.
`exclusion_collection_master_ids`	array of string	Collections whose products are removed, by PIM id.
`exclusion_conditions`	array of object	Value rules that remove products.
`exclusion_match_mode`	string, one of `ALL`, `ANY`	How the exclusion conditions combine.
`exclusion_product_master_ids`	array of string	Products removed by name, by PIM id.
`match_mode`	string, one of `ALL`, `ANY`	How the conditions combine.
`selection_entries`	array of object	Hand-picked products (and variants), by PIM id.
`source_type`	string, one of `PRODUCTS`, `VARIANTS`, `COLLECTIONS`	What the source selects (default PRODUCTS, or COLLECTIONS when collection_master_ids is given).
`title`	string	The source title (default: the next free "Source N").

Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.

update_collection_source_v1

update_collection_source_v1pim:write

Edit one store's source: every field given REPLACES that part wholesale (the whole condition set, the whole hand-picked selection, the whole named-product exclusion, the whole excluded-collection set, the whole value-rule exclusion set); an omitted field is left alone, and an empty list clears it. Conditions sources only — a sub-collections source, an app-owned or locked source, or one already staged for removal is refused. The change ships with the collection's next publish_master_v1.

Argument	Type	Description
`source_projection_id`	string, required	The source's projection id (from get_collection_sources_v1's editing map).
`conditions`	array of object	The rule conditions.
`exclusion_collection_master_ids`	array of string	Collections whose products are removed, by PIM id.
`exclusion_conditions`	array of object	Value rules that remove products.
`exclusion_match_mode`	string, one of `ALL`, `ANY`	How the exclusion conditions combine.
`exclusion_product_master_ids`	array of string	Products removed by name, by PIM id.
`match_mode`	string, one of `ALL`, `ANY`	How the conditions combine.
`selection_entries`	array of object	Hand-picked products (and variants), by PIM id.

Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.

copy_collection_source_v1

copy_collection_source_v1pim:write

Copy one source to another store the collection is on (a store that already has it answers 409), or — with the source's own store as target — duplicate it in place with a " copy" title. Referenced items are re-resolved on the target through the shared PIM items; an item the target lacks is dropped and was named by get_collection_source_copy_preflight_v1. The copy lands as a draft the target store's next publish ships.

Argument	Type	Description
`source_projection_id`	string, required	The source's projection id.
`target_channel_id`	string, required	The store to copy to (the source's own store duplicates in place).

Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.

replace_collection_store_sources_v1

replace_collection_store_sources_v1pim:write

Replace one store's ENTIRE source definition with another store's: the target's current sources are staged for removal and every source of the acting store lands there as a draft, in evaluation order. Destructive for the target store's definition (the removal ships with the next publish). Check get_collection_source_copy_preflight_v1 first for blocked targets and missing items.

Argument	Type	Description
`collection_id`	string, required	The collection id.
`source_channel_id`	string, required	The store whose definition is copied.
`target_channel_id`	string, required	The store whose definition is replaced.

Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.

copy_collection_sources_to_all_stores_v1

copy_collection_sources_to_all_stores_v1pim:write

Copy one store's whole source definition to every other store the collection is on, replacing each target's definition (each target's current sources are staged for removal). Per-store outcome rows: blocked stores (with the reason), failed stores (with the reason), and copied stores with their copied count and missing items. A failure on one store does not stop the others.

Argument	Type	Description
`collection_id`	string, required	The collection id.
`source_channel_id`	string, required	The store whose definition is copied.

Extended timeout. 120 s per call — the operation runs server-side orchestration or a live Shopify read.
Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.