### 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` Up to 100. Up to 100. ### 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` Which currency's prices to change, for example usd. Fixed change in minor units, added to every selected price. -500 takes 5.00 off. Give this or percent, not both. False or omitted previews the change and writes nothing. True performs it. Always preview first and show the merchant the table. Percentage change. 10 raises every selected price by 10%, -15 cuts them by 15%. Give this or amount_minor, not both. Optional. Snap every new price to the NEAREST price ending this way, so a 10% rise on 999.00 lands on a sellable number instead of 1098.90. Omit for exact arithmetic. Not available on currencies with no minor unit, such as JPY. Only products with this status: published or draft. Omit for both. Only products whose title contains this text, case-insensitive. Omit to select the whole catalogue. ### 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` URL slug, unique in this store, for example summer-sale. Optional product ids to add immediately. Up to 100. ### 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` Three-letter code the prices below are in, for example usd. Must be this store's default currency; any other is refused rather than converted. URL slug, unique in this store, for example blue-tee. Required; a duplicate is refused rather than renamed. Shopper-facing product name, 2 to 150 characters. Optional long description. HTML is stored as given. Image URLs, which must be http or https. Use add_media first for local files. Variant axes, for example Size with values S, M, L. These can ONLY be set here: there is no way to add an option or a value to a product later. Price in MINOR units (2999 means 29.99) for a single-variant product. Omit when giving a variants array. 0 means free and is taken literally. One entry per purchasable configuration. Each needs its own price_minor. Brand or manufacturer, for example Ridgeline Supply. Shown on the product page and published as the product's brand in search-engine structured data, so leave it out for an own-label product rather than naming the store. ### 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` The product id, or its handle, for example blue-tee. ### 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` How many. Defaults to 50. ### 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` The next_cursor from a previous call, to get the following page. How many, 1 to 100. Defaults to 20. Only published or only draft products. Omit for both. ### 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` Only needed when publishing is refused because some variants are free and some are priced. Set it after checking the zero prices are intended. True removes the product from the storefront instead of publishing it. Reversible: publish it again to bring it back. ### 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` true archives it; false restores it. From create_collection or list_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` Three-letter code, for example usd. Must be a currency this store has configured. Minor units. 2999 means 29.99. 0 means free and is taken literally. Optional was-price for a sale. Must be strictly greater than price_minor. ### 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` Category ids come from the store's category tree in the dashboard; no tool on this surface lists them yet. Absolute http(s) URL the search engine should treat as this page's real address. "" clears it. SEO description, up to 500 characters. This is the snippet under the headline in a search result. SEO title, up to 255 characters. This is what a search result shows as the page's headline. True keeps this page out of search results. Omit it to leave the stored setting alone; sending false puts the page back into search results. Absolute http(s) URL of the social-preview image, shown when the page is shared. "" clears it. ### 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` From create_collection or list_collections. Absolute http(s) URL the search engine should treat as this page's real address. "" clears it. SEO description, up to 500 characters. This is the snippet under the headline in a search result. SEO title, up to 255 characters. This is what a search result shows as the page's headline. True keeps this page out of search results. Omit it to leave the stored setting alone; sending false puts the page back into search results. Absolute http(s) URL of the social-preview image, shown when the page is shared. "" clears it. ### 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` Absolute http(s) URL the search engine should treat as this page's real address. "" clears it. SEO description, up to 500 characters. SEO title, up to 255 characters. True keeps this page out of search results. Omit it to leave the stored setting alone. Absolute http(s) URL of the social-preview image. "" clears it. Image URL for the product tile. Brand or manufacturer, for example Ridgeline Supply. Published as the product's brand in search-engine structured data. "" clears it; leave it out for an own-label product rather than naming the store.