Shopify Storefront catalog and shipping quotes

Use this guide to connect Shopify's Storefront GraphQL API to Answers. It covers the Shopify configuration as well as the WordPress settings. Start with a test store and a non-production conversation profile.

Choose the right connection​

Connection	Configure it in	Purpose
Shopify UCP catalog, including the shopify-storefront-catalog preset	Answers guided setup / approved MCP tools	Reviewed catalog operations exposed by the remote MCP service
Typed Shopify Storefront adapter	Conversation profile → Tools → External REST read tools	Fixed Storefront GraphQL searches, exact product reads and shop capabilities
Shipping quote consent	The typed adapter's separate shipping quote setting	Prepare a visible form; create a quote cart only after visitor confirmation

The UCP preset's name does not mean that it enables the typed adapter. Adding an MCP connection does not automatically add inventory reads, cart permissions or shipping estimates. The typed adapter uses a code-owned GraphQL request over HTTPS POST; the assistant cannot supply arbitrary GraphQL or change the merchant.

For the guided UCP connection and WordPress product-page links, see Answers setup. If both connections remain enabled, give their purposes distinct wording so inventory and quote requests use the typed Storefront tools. Avoid two indistinguishable catalog-search tools.

1. Prepare the Shopify store​

Confirm the original your-store.myshopify.com domain in Shopify's domain settings. The connector needs that exact hostname, not your storefront's custom domain, an admin URL or a product URL.

Prepare representative products before testing: published products, named variants, prices in the intended market, inventory tracking where applicable and an intentionally unavailable item. Make the products available to the relevant storefront/app sales channel. Availability on the Online Store alone does not prove availability through another channel. Shopify documents channel publication and storefront permission management in Manage the Headless channel.

Choose one provisioning route below. You do not need both apps for one connection.

Route A: Shopify Headless channel​

1. With Shopify app/channel administration permission, install Shopify's Headless sales channel.
2. Open the channel and create a storefront for this integration.
3. Open that storefront's Storefront API permissions → Edit and approve the required access listed below. Save the configuration.
4. Arrange secure backend provisioning of the appropriate Storefront token. The current AI Kit editor uses the public Storefront token type, but keeps its value server-side. Do not paste either token into the conversation profile.

Shopify provides both public and private tokens in this flow. Their authentication headers differ; a private token cannot be substituted into a public-token field. See Getting started with the Storefront API.

Route B: A developer-managed app​

1. In Shopify's Dev Dashboard → Apps, create an app and configure an app version with the required Storefront scopes.
2. Release the app configuration, then use Install app from its Installs card and approve installation on the intended store.
3. Have the integration operator authenticate the app using Shopify's supported installation/authentication flow. Client-credentials authentication is for eligible stores belonging to the app's own organization; it is not a general replacement for another merchant's OAuth installation.
4. Using the authenticated Admin API during provisioning, create a Storefront access token and verify its granted scopes. Store only that Storefront token in the runtime parameter used by this connector. An Admin API token, client secret and Storefront token are different credentials.
5. After changing scopes, release the updated configuration and have the merchant approve the new access. Verify the installed grant and the runtime token's access; changing a draft app configuration is insufficient.

Follow Shopify's Dev Dashboard app guide for installation and approval. The provisioning operation is documented in storefrontAccessTokenCreate. AI Kit does not perform these administrative operations for you. Do not use an old “create private app” tutorial as a substitute for the current Shopify flow.

Required permissions​

Storefront scope	Needed for
unauthenticated_read_product_listings	Products, collections and variants used by catalog reads
unauthenticated_read_product_inventory	The returned variant quantity used by quantity predicates
unauthenticated_read_product_tags	Product tags returned and checked by this adapter
unauthenticated_read_checkouts	Optional quote-cart reads
unauthenticated_write_checkouts	Optional, explicitly confirmed quote-cart creation

The first three are the catalog configuration. Add the last two only when the owner explicitly enables shipping quotes. Shopify's checkout-named permissions cover the Cart API and are broader than this integration's limited quote use; they are not “quote-only” permissions. The integration does not order or pay. Review the installed grant against Shopify's Storefront access-scope reference.

2. Prepare filters and source data​

Install or open Shopify Search & Discovery and configure the storefront filters you intend to use. Availability and price are default filters; vendor, product type, tags and variant options need appropriate shop configuration. Use actual option names and values, such as Color and Ice, rather than assuming a color from a product photograph. See Shopify's filter configuration guide.

The adapter sends supported price, availability, vendor, product-type, tag and variant-option filters to Shopify. It also validates returned facts in backend code: combined price, availability, option and quantity requirements must hold for the same variant. A cheap variant and a different well-stocked variant must not be combined into a fictitious matching offer.

Shopify's Storefront ProductFilter does not provide a minimum-stock-quantity predicate. minQuantity is therefore checked deterministically by the backend against returned variant inventory, not by asking the model to filter a page. Do not use Admin API search syntax as if it were supported by Storefront search.

The nullable quantityAvailable field describes sellable variant quantity for online channels, not a warehouse-by-warehouse inventory guarantee. Unknown quantity is not zero; “available for sale” is not an exact quantity or a delivery promise. For rating predicates, the adapter reads the supported reviews.rating metafield when available. Missing or inaccessible ratings remain unknown; configuring a filter does not create product data.

Complete logical pages with Deployment Access v1.0.130​

With Deployment Access template v1.0.129, backend validation operates on a provider page. Local predicates can leave fewer visible matches than the requested page size while Shopify still has more source pages. An empty filtered page does not establish catalog-wide absence.

From Deployment Access template v1.0.130, the adapter builds a logical page of verified matches in backend code. It preserves every filter on subsequent reads, fills the approved page size and looks ahead for one additional verified match before advertising more results. Its continuation resumes after the last displayed product, so fetched overflow is not silently skipped. A short final page is valid only after the remaining provider search is exhausted.

Keyword searches use Shopify's relevance ordering; browsing without a keyword uses price ordering. The original search and ordering remain bound to each continuation. Next/previous navigation does not ask the model to search again or filter cards. Page size is the approved display-template size, not a total count. The assistant must preserve the visitor's requested search terms; an unexpected extra keyword can narrow results even when pagination itself works correctly.

This is bounded work, not an unlimited catalog scan: at most eight provider requests, a shared 15-second limit (or an earlier parent deadline), and aggregate response-size limits. If these limits, unknown required inventory, incomplete variant coverage or Shopify's search ceiling prevent a reliable result, the operation reports an incomplete search, not “no matches.” Narrow the search or correct missing data before retrying. Shopify itself limits a search to 1,000 results; this is not proof that a larger catalog ends there. A displayed result count is not automatically the catalog's total match count.

If the visitor does not request an availability restriction, the adapter combines the available/unavailable search partitions without adding an orderability filter on their behalf. An explicit stock minimum remains a separate typed condition; it is not satisfied merely by an “Available to order” badge.

3. Provision the backend reference​

Ask the backend operator to provision the Storefront credential securely as an app-owned encrypted runtime parameter and grant the deployed runtime access. The profile accepts its name, for example /APPNAME/external-tools/storefront-token, not its contents. APPNAME must be the actual deployment's application prefix. A plaintext parameter is rejected.

Never put token values in profile JSON, fixed headers, source-control files, screenshots, support tickets or chat. The browser and model do not need them. Credential rotation belongs to the operator's secret-management procedure; after rotation verify a read through the intended deployment without displaying the credential.

The current WordPress Storefront editor fixes authentication to X-Shopify-Storefront-Access-Token. Backend support for Shopify-Storefront-Private-Token exists, but it is not a token-type selector in this editor. Do not paste a private token into the public-token configuration. An operator-managed private-token integration also requires a trusted visitor IP from the backend's request context; no placeholder IP or browser-supplied tool argument is acceptable. Shopify explains these distinct headers in its Storefront authentication reference.

4. Add the typed tools in WordPress​

Open SmartCloud → Answers → detailed settings → Conversation profile → Tools. In External REST read tools, add a tool and choose Shopify Storefront (read only) as the adapter. Repeat for each required operation:

Example tool ID	Storefront read operation	Suggested purpose
shopify-products	Search products	Find products using supported price, availability, quantity and option conditions
shopify-product	Get one product	Read a previously verified exact Shopify product ID and its returned variants
shopify-capabilities	Read shop capabilities	Read general shop capabilities, without promising checkout eligibility

These IDs are examples, not required names. Use distinct IDs and clear purposes. Different operations can share one merchant endpoint; do not duplicate the same operation on that endpoint.

For each tool:

1. Enter the original Shopify shop domain and select its operation.
2. Enter the Storefront token SSM parameter name supplied by the operator.
3. Check the read-only Derived Storefront endpoint: https://your-store.myshopify.com/api/2026-10/graphql.json. This adapter pins API version 2026-10; the field is not an arbitrary endpoint or API-version editor.
4. Under Market and language, optionally choose the country code and a Shopify-published language. Leaving these empty uses shop defaults. A language is not a currency conversion; returned prices and currencies remain source facts. Keep market and credential settings consistent across the three tools.
5. Leave Offer separately confirmed shipping quotes off until completing the consent and permission review below.
6. Enable the reviewed tools and Save profile. Opening or editing a tool only changes the draft. Configure the assistant's purpose to use these tools for live facts rather than treating knowledge-base product text as current stock.

No custom GraphQL body, free-form query-parameter mapping or model-generated response schema is required. The typed adapter supplies its approved input and output contract.

5. Configure verified cards and labels​

In Display templates, enable structured displays and add a template bound to the approved Storefront read source. Choose the intended layout and page size. Review title, description, image, price, quantity and navigation mappings against a verified sample from that source. Preview arguments are inputs for a real approved read, not a place to paste a fabricated product response. Use a known search or verified product ID, according to the selected source operation.

Apply the template to the profile draft, then save the conversation profile. The backend materializes cards from verified records. The assistant may provide a concise grounded introduction or comparison, but must not regenerate or change the source price, currency, inventory, IDs or variant facts in the cards.

Configure card and paging labels through the shared translation catalog. Labels follow the chatbot UI/site locale; answer prose may follow the visitor's question language. Missing translations retain the authored source label. A model pass does not translate every card field, product name or stored record.

Explicit HTML/Markdown text formats for mirrored structured WordPress content are a separate feature, not permission to render arbitrary Shopify HTML. After reviewing field-format mappings and completing synchronization, declared HTML defaults to readable plain text. A structured-content template can separately opt into Allow safe rich-text formatting, requiring compatible display-policy version 4 and wire version 3. That restricted formatting does not enable raw HTML, links or images in a text property. Plain or unmarked fields remain plain.

6. Enable separately confirmed shipping estimates​

Before enabling quotes, approve the two cart scopes, verify the merchant's shipping configuration and review your site's privacy notice. Explain that the entered delivery details go to the configured merchant and through private backend processing, and that Shopify may retain the created cart under the merchant's policies. Do not describe it as automatically deleted on closing chat.

Enable Offer separately confirmed shipping quotes on the catalog tools whose returned variants may be used for quotes, particularly Search products and Get one product. Save the profile. This flag does not install an app or grant Shopify permissions. Enabling it only on a capabilities read cannot supply product variants.

The intended visitor flow is:

1. The visitor requests a quote for a product, exact variant and quantity.
2. The assistant reads current source data and resolves the variant. If it is ambiguous, it asks a clarification rather than guessing.
3. A Check shipping quote form shows the verified items and requests delivery details. Preparing the form does not create a cart or calculate shipping.
4. Only the visitor's explicit submission authorizes temporary cart creation and rate retrieval. No option is selected, no order is placed and no payment occurs.
5. The result shows returned estimates, pending/unavailable status or a failure. A pending estimate for a known cart may be refreshed without creating another cart. If cart creation has an uncertain outcome, the backend does not blindly repeat that mutation.

Use the form, not ordinary chat, for delivery inputs. The structured values do not enter model prompts, visible chat history or browser conversation storage. Private cart references remain server-side. Quote proposals expire and are bound to the conversation and reviewed profile; start a fresh request after expiry or a profile change.

Shopify estimates depend on the concrete cart and destination. This integration does not promise an arrival date or determine checkout-specific payment methods. General supported card brands/wallets are not evidence that a specific purchase can use them. Shipping options and totals may change at checkout; do not add an option's estimate to a displayed cart total and present it as a final payable amount. See Shopify's Cart API and cart creation.

7. Verify the complete experience​

Test against your own known Shopify records, not guessed inventory:

• Search a known product, then read its exact variant. Compare title, option, amount, currency and quantity with the same market/channel in Shopify.
• Combine a price limit, minimum quantity and variant option. Confirm that one variant satisfies them all; test a product whose different variants satisfy different individual conditions.
• Check next/previous navigation, sparse matches, a genuinely absent product and explicit incomplete-search outcomes with Deployment Access template v1.0.130 or later. Include keyword searches with both availability and minimum quantity. Never infer whole-catalog absence from one page, and start a fresh search after a backend upgrade.
• Request a shipping quote. Confirm that the visible form appears before any cart creation, and that abandoning it does not create a cart. Test submission only with a deliberately approved test destination, then test pending refresh.
• Test missing permissions, unavailable quantity and unsupported delivery destinations. They must not become invented stock, free shipping or guarantees.
• Ask in another language while keeping the site locale unchanged. Check answer language separately from catalog-translated UI labels and source product facts.

The demo may be tested directly in WordPress after its access protection. A static frontend is not a prerequisite. For a separately exported static site, republish its frontend assets after updating the plugin; saved replies and old exports are not retroactively rewritten.

Troubleshooting​

Symptom	Check
The assistant uses generic catalog data or says it cannot check shipping	Confirm the typed tools are enabled in the saved profile, have distinct purposes, and quote consent is enabled on the source returning the verified variant. UCP setup alone is insufficient. Inspect tool activity; do not assume a model response proves a tool ran.
A token works elsewhere but this connector fails	Check exact store, runtime parameter ownership/type, installed grants, and token type. Admin tokens and private Storefront tokens are not interchangeable with the public Storefront token configured by the UI.
A product is missing	Check channel publication, market availability, search terms and enabled Search & Discovery filters. Compare the same source and market, not only the Online Store page.
Available quantity is unknown	Verify inventory permission and the returned field. Missing inventory must remain unknown; availability alone does not establish ten items in stock.
Two results appear on a three-item page with more source pages	This can occur with Deployment Access template v1.0.129 page-local validation. Update the Deployment Access stack to template v1.0.130 or later and start a fresh search; a plugin update alone does not activate the complete logical-page backend behavior.
Next results fails after an upgrade	Start a fresh search instead of reusing an expired or old-protocol continuation. If a fresh request still fails, collect its correlation ID and sanitized backend status; do not hide a provider cursor cycle as an empty result.
Search is explicitly incomplete	Narrow the query or resolve missing required data. The bounded scan could not prove a complete matching page or exhaustion; this is not “no results.”
A quote remains pending or unavailable	Inspect cart scopes, merchant shipping rates/destination and sanitized backend status. Refresh only the known pending cart. Do not repeatedly create carts after an uncertain outcome.
Cards have different-language labels from the answer	Expected when UI locale and question language differ. Add the authored labels to the shared translation catalog; absence of a translation retains the source label.
A change appears saved locally but visitors see old behavior	Apply nested drafts, save the conversation profile, confirm the intended backend/site, and republish static frontend assets if applicable. Start a fresh test conversation.

For support, collect the deployment/release identifier, tool ID and operation, profile revision, time, request correlation ID and sanitized failure category. Do not include credentials, private cart IDs or delivery addresses in logs or screenshots supplied for troubleshooting.