Catalogue tools

​

add_products_to_collection

Adds products to a collection and removes others, in one call. Safe to repeat: adding a product already in the collection and removing one that is not there both do nothing rather than failing, so a retry cannot get this into a half-applied state. Scope: write_collections

​

bulk_update_prices

Changes many prices at once by a percentage or a fixed amount, for the whole catalogue or for products matching a title. PREVIEWS BY DEFAULT: it returns the table of before and after prices and writes nothing until apply is true. Every new price is checked before any of them is written, so a change that would be rejected partway through is refused whole instead of leaving the catalogue priced two ways. Scope: write_products

​

create_collection

Creates a collection, which is a named group of products shoppers can browse, and optionally puts products in it straight away. handle is required and is the collection’s URL slug; a duplicate is refused rather than renamed, so retrying a call that already worked cannot create a second collection. Scope: write_collections

​

create_product

Creates a product in this store as a DRAFT, with its variants, options and images. Nothing is visible to shoppers until publish_product is called. handle and currency_code are required: the handle is what makes a retry refuse instead of creating a second product, and the currency is checked against the store because a price is stored as a plain number with no currency attached to it. Give either price_minor for a single-variant product, or a variants array, not both. Scope: write_products

​

get_product

Reads one product by its id or its handle, with its description, status and every variant’s id and price. Use it before editing a product, so the edit starts from what is actually there. Scope: read_products

​

list_collections

Lists this store’s collections with their ids, handles and how many products each holds. Call this to get the collection_id that add_products_to_collection needs. Scope: read_collections

​

list_products

Lists this store’s products, newest first, with each one’s variants and their ids and prices. Call this to answer anything about what the store sells, and to get the product_id and variant_id every other catalogue tool needs. Scope: read_products

​

publish_product

Makes a draft product visible to shoppers, or hides a published one when hide is true. Hiding is the reversible way to take something off the storefront; there is no tool that deletes a product, because deleting one would also destroy the downloads and subscriptions customers have already paid for. Scope: write_products

​

set_collection_status

Archives or unarchives a collection. Archiving removes it from every storefront listing and its own page without deleting it: the collection, its product links and everything else about it are untouched, and unarchiving restores it exactly as it was. This is how to retire a collection an automation created by mistake or no longer needs; there is no delete tool because a collection delete would take its product links with it and there is no route to undo that. Safe to call on a collection already in the requested state. Scope: write_collections

​

set_variant_price

Sets what shoppers pay for one variant, in one currency. Prices are in MINOR units, so 2999 means 29.99. compare_at_minor is the struck-through was-price and must be higher than the price. Call get_store_layout or create_product first if you do not have the variant id. Scope: write_products

​

update_category_seo

Sets what search engines and social cards show for a category’s page: its title, its description, the canonical URL, the social-preview image, and whether the page is indexed at all. Only the fields given are changed; everything omitted keeps its stored value, and "" on a URL clears it. These are the fields the storefront actually renders into the page head: without them the page falls back to the category’s own title. Scope: write_categories

​

update_collection_seo

Sets what search engines and social cards show for a collection’s page: its title, its description, the canonical URL, the social-preview image, and whether the page is indexed at all. Only the fields given are changed; everything omitted keeps its stored value, and "" on a URL clears it. These are the fields the storefront actually renders into the page head: without them the page falls back to the collection’s own title. Scope: write_collections

​

update_product

Edits a product’s text fields, its brand, and the head tags search engines read. Only the fields given are changed; everything omitted keeps its stored value, so a call that sends only a title cannot blank the description. Setting canonical_url, og_image_url or no_index also stores meta_title and meta_description where the storefront renders them, and doing that invalidates any translations of that meta text. Does not change price (use set_variant_price) or visibility (use publish_product). Scope: write_products