Shopigent Shopigent

Tools Reference

Shopigent exposes 87 distinct seeded merchant tools across nine categories. Each category can be toggled on/off per store, and destructive write tools default to the confirmation gate. Runtime-only connection identity and capability utilities (get_connection_identity, get_connection_capabilities, registered by the MCP server rather than seeded) are listed separately and are not included in the 87-tool catalog count.

Tools are curated operations, not raw API passthrough — inputs are validated, outputs are trimmed to what agents actually need, and destructive calls default to requiring human approval.

Plans at a glance

Plan Daily calls Access
Free 25/day Reads, plus dry-run previews of writes (never executed)
Growth 500/day All writes except premium tools
Pro No daily cap (60/min fair use) Everything, including general Shopify resource translations

Premium (Pro-only) tools: set_translations, get_translations, delete_translations.

Products (31)

Tool Type Plan What it does
list_products Read Free Paginated list of products, optionally filtered by a search query.
search_products Read Free Full-text search across product titles, descriptions, and tags with relevance scoring.
get_product_by_id Read Free Fetch a single product by its Shopify GID.
create_product Write Growth Creates a product with optional description, status, vendor, type, tags, options, and default-variant price.
update_product Write Growth Updates a product's fields including title, description, status, vendor, type, tags, SEO, handle, and template (templateSuffix / clearTemplateSuffix).
delete_product Write Growth Permanently deletes a product. Irreversible.
create_product_variant Write Growth Adds a variant with price, SKU, barcode, and option values to an existing product.
update_product_variant Write Growth Sets SKU, price, barcode, and option values on an existing product variant.
update_product_variant_price Write Growth Sets the price of a single product variant by its GID.
update_product_variant_weight Write Growth Safely updates only a variant's shipping weight. Supports grams, kilograms, ounces, and pounds; live writes always require confirmation.
bulk_update_prices Write Growth Sets prices for a list of variants on one product. dryRun returns one wouldChange diff and does not write. Free can preview and cannot execute. Growth and Pro execute with this tool's confirmation setting, which is on by default.
update_product_images Write Growth Manages product images (add, update alt text, delete) via the Shopify Media API.
upload_product_media Write Growth Uploads media to a product using Shopify's staged-upload flow. Prerequisites: a verified live grant containing write_products, read_files and write_files. Requires confirmation.
get_product_media Read Free Lists media attached to a product.
get_product_publications Read Free Lists where a product is published (channels, online store, etc.).
list_publications Read Free Lists this store's sales-channel publications, channel labels, and authoritative IDs for explicit selection.
publish_product_to_channel Write Growth Publishes one product to one explicitly selected publication. A dry-run does not publish. A live call always requires confirmation.
get_product_metafields Read Free Reads metafields attached to a product.
set_product_metafields Write Growth Writes or updates one or more product metafields.
get_store_info Read Free Returns store-level information: name, email, currency, timezone, and plan.
list_collections Read Free Lists all collections (manual + automated) with id, title, handle, and sort order.
get_collection_by_id Read Free Fetches a single collection by its GID, including description, image, product count.
create_collection Write Growth Creates a new manual or automated collection.
update_collection Write Growth Updates a collection's title, description, handle, sort order, and/or SEO.
delete_collection Write Growth Deletes a collection by its GID.
add_products_to_collection Write Growth Adds one or more products to a collection.
remove_products_from_collection Write Growth Removes one or more products from a collection.
update_collection_image Write Growth Adds, updates, or deletes a collection's image.
get_translations Read Pro Reads all translatable content for a resource (product, collection, page, etc.) in a locale.
set_translations Write Pro Writes or updates translation values for a resource in a locale.
delete_translations Write Pro Removes translation overrides for given keys in a locale.

Publication tools: exact contracts

list_publications

Use this read-only tool before publishing to obtain publication IDs and the channel names and handles that belong to the connected store. The user or agent must choose one returned publicationId explicitly; Shopigent does not select a target by matching a channel name.

Inputs:

Field Required Rules
first No Number of publications per page; defaults to 25 and is capped at 50.
after No Opaque pagination cursor from the previous pageInfo.endCursor.
catalogType No Exact filter: APP, COMPANY_LOCATION, or MARKET.

The result contains publications[] with each publication's ID, automatic/future-publishing flags, catalog identity, and channels[] (id, name, handle, specificationHandle, and app identity when available), plus pageInfo.hasNextPage and pageInfo.endCursor. It requires publication read access and performs no write or confirmation flow.

publish_product_to_channel

This compound write establishes one publication edge for one product. It requires an authoritative live grant for both writeProducts and writePublications; a configured or cached scope is not enough. If either capability is missing or cannot be verified, the call fails closed before any write. write_publications is optional and can be enabled or revoked from Scopes & Permissions without affecting the rest of the catalog.

Inputs:

Field Required Rules
productId Yes Canonical gid://shopify/Product/... ID.
publicationId Yes Canonical gid://shopify/Publication/... ID selected from list_publications.
activateProduct Yes Explicit boolean. No default: the user decides whether a draft product may become active.
idempotencyKey Yes Stable 8–128 character key using letters, numbers, ., _, :, or -.
stateFingerprint Confirmed call only Server-issued state fingerprint from the preview; prevents execution of a stale plan.

Before any mutation, the tool verifies that the product and publication belong to the connected store and reads the current product status and target publication edge. A dryRun: true call returns that product, the selected publication, the intended final state, and a state fingerprint, with zero mutations.

Every live call requires human confirmation even if a store-level confirmation toggle is off. The confirmation is bound to the store, tool, product ID, publication ID, activation choice, idempotency key, and state fingerprint. The confirmed call must resend the exact fields requested by the preview together with confirmed and the confirmation token. Expired, replayed, mismatched, or stale confirmations are rejected.

Idempotency is scoped to the store and this tool. Reusing a key for a different target is rejected. A retry reads live state rather than trusting an earlier audit entry; if a merchant changed a previously successful target afterward, the caller must use a new key instead of silently restoring that state.

The workflow publishes the selected edge first when possible and activates the product only when the confirmed activateProduct choice requires it. Success is reported only after readback confirms the requested state. If a later step fails after this operation created the edge, compensation may remove only that newly created target edge and roll back a status change made by the same operation. It never removes a pre-existing edge. Partial or unknown final states return a structured error with the failed phase, final readback when available, mutations attempted, and compensation results; they are never reported as successful publication.

This tool does not change product media, prices, inventory, SEO, tags, templates, translations, or any other channel. It does not accept a channel name, a publish date, multiple publication IDs, or an "all channels" option.

upload_product_media — capability contract and retry semantics

Prerequisites

This tool requires a verified live OAuth grant that includes write_products, read_files and write_files (see the Scopes reference). Neither a configured scope string nor a stored offline session scope counts as proof — only an authoritative live-grant snapshot from Shopify is accepted. If any of these prerequisites is missing from the live grant, the call fails before the upload payload is decoded, before any staged target is requested, and before a confirmation token is issued.

Capability response

The server's get_connection_capabilities tool returns capabilities.uploadProductMedia as true only when a verified live grant contains write_products, read_files, and write_files. That tool response does not include capabilityGaps. capabilities.uploadProductMedia is the boolean the tool returns. It is false when the live grant is missing any of those scopes or when the live grant cannot be verified. Configured scopes in the app environment are not treated as a live grant.

Confirmation gate

upload_product_media always requires human confirmation. The dry-run preview (dryRun: true) validates the files and returns a plan of the steps it would take, including a staged-upload step. It does not call Shopify and it does not upload. Every live call that passes the capability gate issues a signed, single-use confirmation token bound to:

The initial confirmation response includes a content.resendRequired field set to "full_identical_payload". The agent must present the complete identical payload together with the confirmation token; a token alone is not enough to resume after expiry. This is an explicit design choice (SH-014 Option A was chosen over Option B): the server does not store upload payloads, so every retry after a 25-minute token TTL must re-send the full files and arguments. The confirmation gate accepts a previously used token for retry purposes as long as the args hash matches, the shop matches, and the token is not expired — this allows the agent to retry the identical call after a partially completed workflow without re-confirming.

Retry contract with idempotency

The upload workflow uses idempotency keys across the multi-step pipeline:

Observability stages

Each upload emits a structured JSON log entry at every pipeline stage:

  1. stagedUploadsCreate — requesting signed targets
  2. confirmation_issued — token created with args-hash binding
  3. binary_upload — PUT'ing each file (per-file reporting)
  4. fileCreate — registering uploaded files as MediaImage records
  5. file_status_polling — waiting for READY status (with bounded timeout)
  6. productSet — attaching to product gallery in order
  7. final_readback — confirming the expected gallery state

These logs carry the stage name, shop ID, operation ID, product ID, file count, and (on error) a sanitized diagnostic excerpt and Shopify request ID. They never contain tokens, headers, confirmation tokens, base64 payloads, or staged target parameters. See Security & Trust for the logging rules.

Content (16)

Tool Type Plan What it does
list_pages Read Free Lists all pages with id, title, handle, and status.
get_page_by_id Read Free Fetches a single page by its GID, including body and SEO metadata.
create_page Write Growth Creates a new online store page.
update_page Write Growth Updates a page's title, body, and/or handle.
delete_page Write Growth Deletes a page by its GID.
list_blogs Read Free Lists all blogs with id, title, handle, and comment policy.
get_blog_by_id Read Free Fetches a single blog by its GID, including its articles and metadata.
create_blog Write Growth Creates a new blog.
update_blog Write Growth Updates a blog's title and/or handle.
delete_blog Write Growth Deletes a blog by its GID.
list_articles Read Free Lists all blog articles for a blog, with optional filters.
get_article_by_id Read Free Fetches a single blog article by its GID, including body, summary, tags, author.
create_article Write Growth Creates a new blog post (article) under a blog.
update_article Write Growth Updates a blog post's title, body, summary, handle, tags, author.
delete_article Write Growth Deletes a blog post by its GID.
update_article_image Write Growth Adds, updates, or deletes a blog article's featured image.

Metaobjects / Custom Data (15)

Access to Custom Data (metaobjects & metafield definitions) requires a dedicated scope category in Scopes & Permissions.

Tool Type Plan What it does
list_metaobjects Read Free Lists metaobjects of a given type.
list_metaobject_definitions Read Free Lists metaobject definitions.
get_metaobject Read Free Fetches a single metaobject by its GID.
create_metaobject Write Growth Creates a new metaobject.
update_metaobject Write Growth Updates an existing metaobject.
delete_metaobject Write Growth Deletes a metaobject. Destructive.
get_metaobject_definition Read Free Fetches a single metaobject definition.
create_metaobject_definition Write Growth Creates a metaobject definition.
update_metaobject_definition Write Growth Updates a metaobject definition.
delete_metaobject_definition Write Growth Deletes a metaobject definition. Destructive.
list_product_metafield_definitions Read Free Lists metafield definitions scoped to products.
get_metafield_definition Read Free Fetches a single metafield definition.
create_metafield_definition Write Growth Creates a metafield definition.
update_metafield_definition Write Growth Updates a metafield definition.
delete_metafield_definition Write Growth Deletes a metafield definition. Destructive.

Orders (6)

Tool Type Plan What it does
list_orders Read Free Paginated list of orders, filterable by status/date/tags.
search_orders Read Free Full-text search across orders by number, customer name, or email.
get_order Read Free Fetches a single order by its GID (line items, addresses, tags, status).
create_order Write Growth Creates an order directly (not a draft) from line items. Optional customer, note, tags, and shipping address. Confirmation is off by default.
update_order Write Growth Updates editable order fields: tags, note, and/or email.
refund_order Write Growth Issues a refund on an order. Irreversible financial action.

Customers (5)

Tool Type Plan What it does
list_customers Read Free Lists store customers with optional filters.
search_customers Read Free Full-text search across customers by name, email, or phone.
get_customer Read Free Fetches a single customer by GID (name, email, phone, tags, note).
create_customer Write Growth Creates a new customer.
update_customer Write Growth Updates first name, last name, email, phone, note, tags, locale, or tax exemption. Pass only the fields to change. Confirmation is on by default.

Discounts (4)

Tool Type Plan What it does
list_discounts Read Free Lists store discounts (discount nodes).
get_discount Read Free Fetches a single discount by its GID node id.
create_discount Write Growth Creates a new discount code or automatic discount.
delete_discount Write Growth Deletes a discount by its GID.

Fulfillments (4)

Tool Type Plan What it does
list_fulfillment_orders Read Free Lists store fulfillment orders.
get_fulfillment_order Read Free Fetches a single fulfillment order by its GID.
close_fulfillment_order Write Growth Closes a fulfillment order (marks it fulfilled/complete).
open_fulfillment_order Write Growth Re-opens a closed fulfillment order.

Inventory (2)

Tool Type Plan What it does
update_inventory_quantity Write Growth Sets the available inventory quantity for an item at a location.
bulk_update_inventory Write Growth Sets available quantities for a list of inventory items at locations. dryRun returns one wouldChange diff and does not write. Free can preview and cannot execute. Growth and Pro execute with this tool's confirmation setting, which is on by default. If the optional inventory scope is not granted, the preview says so and the live call changes nothing.

Theme Pull Requests (4)

The Theme Pull Requests category uses a stored GitHub App installation when one is already saved and the App is configured. Starting a new GitHub App connection on that page is unavailable; the page then says to use a repository-scoped personal access token. If the GitHub App is not configured, the page says the one-click flow is not set up and the token form remains. Shopigent reads only explicitly requested files. A dry-run of github_create_theme_pr returns a preview and does not open a pull request. A live call requires confirmation, then creates a branch, commits the declared changes, and opens a pull request. Valid paths include locales/*.json, templates/*.json, sections/snippets/blocks/*.liquid, assets, and config/settings_data.json. Shopigent never merges the PR, deploys or publishes a theme, or edits Shopify theme code through the Admin Theme API. The merchant reviews and merges. Shopify's native GitHub theme integration then synchronizes the connected branch to the merchant-selected theme. Reviewer demonstrations use an unpublished connected theme so the live storefront remains unchanged; publication remains merchant-controlled.

Tool Type Plan What it does
github_theme_connection Read Free Returns the designated repository connection (owner/repo/defaultBranch) without exposing tokens.
github_list_theme_branches Read Free Lists branches on the connected repository. Read-only.
github_theme_file Read Free Reads one explicitly named repository file at a ref and returns path, branch, SHA, and content.
github_create_theme_pr Write Growth Creates a branch, commits the declared file changes, and opens a PR on the connected theme repo. PR-only — never merges, deploys, or publishes. Confirmation required (approved in your AI client or on the Confirmations page); dry-run available. The Theme Pull Requests page shows the latest stored dry-run or pending-confirmation plan, including files and branch, and labels it not executed. That page does not create, merge, or publish a pull request.

Runtime utilities (not counted in the 87-tool catalog)

get_connection_identity and get_connection_capabilities are registered directly by the MCP server (not seeded as catalog tools) and provide connection metadata only. They are excluded from the published catalog count. (get_store_info is a seeded catalog tool and is counted above.)

Cross-cutting features