Authenticate with a Storefront API access token (public or private); include it in every request as the X-Shopify-Storefront-Access-Token header.
Send a GraphQL POST to https://{shop}.myshopify.com/api/{version}/graphql.json with the predictiveSearch query, passing the search {query} variable and a types argument listing the resource types to include (e.g., [PRODUCT, COLLECTION, PAGE]).
Parse PredictiveSearchResult from the response: it contains products, collections, pages, articles, and queries arrays; render each group with appropriate UI (product thumbnail + title, collection name, query chips).
Control result quantity per type using limit and limitScope — when limitScope is EACH, the limit applies individually to each resource type; when ALL, it applies to the total.
Debounce user input and cancel in-flight requests when a new keystroke arrives to avoid race conditions and excessive API calls.
Known gotchas
The predictiveSearch query is only available on the Storefront API — it is not available on the Admin API. Ensure you are using the correct endpoint and token.
Search results surface products whose status is ACTIVE and that are available in the sales channel associated with the Storefront API access token; hidden or draft products will not appear.
The Shopify Search & Discovery app controls which filters and search fields are configured; customizations made there (e.g., boosted products, synonyms) affect Storefront API search results as well.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp