--- title: Agentic commerce has arrived description: >- Learn how to build AI agents that can search hundreds of millions of Shopify products, manage universal carts across multiple merchants, and deliver seamless checkout experiences using the Shopify Catalog MCP server and web components. source_url: html: 'https://shopify.dev/docs/agents' md: 'https://shopify.dev/docs/agents.txt' --- ExpandOn this page * [How it works](https://shopify.dev/docs/agents.txt#how-it-works) * [Connect to the MCP server](https://shopify.dev/docs/agents.txt#connect-to-the-mcp-server) * [Find products with the Shopify Catalog](https://shopify.dev/docs/agents.txt#find-products-with-the-shopify-catalog) * [Add products from any store to a Universal Cart](https://shopify.dev/docs/agents.txt#add-products-from-any-store-to-a-universal-cart) * [Initiate checkout with Checkout Kit](https://shopify.dev/docs/agents.txt#initiate-checkout-with-checkout-kit) # Agentic commerce has arrived We're bringing native shopping into your AI conversations. Use our APIs and MCPs to add shopping capabilities to your agent across a vast merchant ecosystem with hundreds of millions of products. Shopify has you covered from querying for products to showing them to buyers. There's no need to worry about all the ways in which products are sold, such as variants, subscriptions, bundles, or kit configurations. It just works. Shopify loads the merchant's checkout, combining the customizations they need to run their business with your agent's branding so it feels native to your application. Meeting common compliance requirements is simple, including GDPR, CCPA, [PCI DSS v4](https://www.shopify.com/ca/partners/blog/checkout-compliance), and more. And because Shopify handles checkout for you, you don't have to worry about the usual marketplace compliance requirements faced by platforms that handle their own payments. Early access The capabilities described on this page are not generally available, and require an invitation from Shopify during the Early access period. [Sign up here for early access to apply](https://docs.google.com/forms/d/e/1FAIpQLSekbYOu7R_HTvuo2bX6DUANgu2fRt1ukSc8Ap0y6JuOf7NTaQ/viewform?usp=dialog) and become an approved agent. *** ## How it works The Shopify Catalog MCP server lets your agent shop across merchants on behalf of a buyer: 1. **[Shopify Catalog](#find-products-with-the-shopify-catalog)**: A buyer asks their AI agent to find a product (for example, "lightweight running shoes"). Your agent calls the `search_catalog` tool to search the Shopify Catalog. The MCP server response includes a search result and a set of product web components. Your agent can render these components directly in the chat to provide rich, inline previews. 2. **[Universal Cart](#add-products-from-any-store-to-a-universal-cart)**: As a buyer adds items to their cart from any number of merchants, your agent can use the `update_cart` tool to update a Universal Cart. The MCP server response includes the cart details with a checkout URL to complete the purchase, and a cart web component, which displays the items and subtotals. 3. **[Checkout Kit](#initiate-checkout-with-checkout-kit)**: Your buyer initiates checkout from the Universal Cart web component, or your agent initiates checkout by calling the Checkout Kit with the checkout URL provided by the Universal Cart. Checkout Kit securely renders the merchant's checkout experience with your agent’s branding overrides for a seamless buyer experience that works across mobile and web. *** ## Connect to the MCP server The Shopify Catalog MCP server is an authenticated endpoint that requires an [authorization bearer token](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/). Every tool call must include the `Content-Type` and `Authorization` HTTP headers. Note The bearer token is a private key provided by Shopify to approved agents, used for server-to-server communication. Ensure it's kept private. ```js fetch('https://catalog.shopify.com/api/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {YOUR_API_TOKEN}' // private API key; do not share }, body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/list', id: 1 }) }); ``` Caution By using the Shopify MCP servers, you agree to the [Shopify API License and Terms of Use](https://www.shopify.com/legal/api-terms). *** ## Find products with the Shopify Catalog The `search_catalog` tool enables your agent to search across hundreds of millions of products. Responses are in a standardized format and provide results clustered to a UPI (Universal Product Identifier) so that search results are not overwhelmed with duplicate products. ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 2, "params": { "name": "search_catalog", "arguments": { "query": "lightweight running shoes", "ships_to": "US", "limit": 5, "context": "buyer prefers light and bright colors" } } } ``` ### Supported arguments | Field | Description | Type | Example Value | | - | - | - | - | | `query` *(required)* | Keyword(s) for search | String | Running Shoes | | `limit` | Maximum number of results to return (defaults to 10, max of 10) | Integer (1-10) | 5 | | `min_price` | Minimum price of products to return. API accepts decimals. | Decimal (currency determined by ships\_to) | 10 | | `max_price` | Maximum price of products to return. API accepts decimals. | Decimal (currency determined by ships\_to) | 100 | | `categories` | Comma-delimited list of global IDs for taxonomy categories. Refer to the [Shopify Standard Product Taxonomy](https://shopify.github.io/product-taxonomy/releases/latest/) and [raw category list](https://github.com/Shopify/product-taxonomy/tree/main/dist/en). | String | For example, for shoes, use: [gid://shopify/TaxonomyCategory/aa-8](https://shopify.github.io/product-taxonomy/releases/2024-10/?categoryId=gid%3A%2F%2Fshopify%2FTaxonomyCategory%2Faa-8) | | `ships_to` | An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. | String | US (default), CA | | `ships_from` | An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. | String | US (default), CA | | `available_for_sale` | Whether to filter available for sale. | Int (0,1) | 0 (false or include not available products), 1 (true or exclude not available products, default) | | `context` | Any additional context on the query that can help future queries surface more relevant results. | String | The user is trying to find some new running shoes to replace their worn out pair. | ### MCP response (Shopify Catalog) The MCP response contains the serialized JSON search results and a set of UI resources with rich web components for each product via [MCP UI](https://mcpui.dev/). These can optionally be used to render rich and interactive product cards. Tip See our blog post on [Breaking the text wall](https://shopify.engineering/mcp-ui-breaking-the-text-wall) for a deep-dive on MCP UI. ```json { "content": [ { "type": "text", "text": "{... search response (see below) ...}" }, { "type": "resource", "resource": { "uri": "ui://product/gid://shopify/Product/123123", "mimeType": "text/uri-list", "text": "https://cdn.shopify.com/storefront/product-summary.component?store_domain=demostore.mock.shop&product_handle=hoodie" } }, ... ] } ``` The deserialized JSON provides a list of products, their options, price ranges, ratings, and one or more stores where each variant is available. In this example, a query for “lightweight running shoes” returns an “awesome running shoe” that is available in two sizes and sold by two different stores: ```json [ { "id": "gid://shopify/p/44r9rYAkQ6IytYTmECwVQ3", "title": "Awesome Running Shoe - White", "description": "[description of the product]", "images": [ { "url": "https://cdn.shopify.com/s/files/...", "altText": "[description of the image]", } ], "options": [ { "name": "shoe size", "values": [ { "value": "US 10", "availableForSale": true, "exists": true }, { "value": "US 11", "availableForSale": true, "exists": true } ] } ], "priceRange": { "min": { "amount": "80.0", "currencyCode": "USD" }, "max": { "amount": "90.0", "currencyCode": "USD" } }, "availableForSale": true, "products": [ { "id": "gid://shopify/Product/1234", "title": "Awesome Running Shoes - White", "checkoutUrl": "https://....", "description": "[description of the product]", "featuredImage": { "url": "https://cdn.shopify.com/s/files/...", "altText": "[description of the image]" }, "onlineStoreUrl": "https://...", "price": { "amount": "80.0", "currencyCode": "USD" }, "rating": { "value": 4.5, "count": 10 }, "availableForSale": true, "shop": { "name": "Snowdevil Shoes", "paymentSettings": { "supportedDigitalWallets": [ "SHOPIFY_PAY" ] }, "onlineStoreUrl": "https://...", "id": "gid://shopify/Shop/[shop_id]", }, "selectedProductVariant": { "id": "gid://shopify/ProductVariant/121212", "options": [ { "name": "shoe size", "value": "US 10" } ], "image": { "url": "https://cdn.shopify.com/s/files/...", "altText": "[description of the image]" }, "availableForSale": true } }, { "id": "gid://shopify/Product/2345", "title": "Awesome Running Shoes", "checkoutUrl": "https://....", "description": "[description of the product]", "featuredImage": { "url": "https://cdn.shopify.com/s/files/...", "altText": "[description of the image]" }, "onlineStoreUrl": "https://...", "price": { "amount": "90.0", "currencyCode": "USD" }, "rating": { "value": 4.9, "count": 50 }, "availableForSale": true, "shop": { "name": "Shoe Shop", "paymentSettings": { "supportedDigitalWallets": [ "SHOPIFY_PAY" ] }, "onlineStoreUrl": "https://...", }, "selectedProductVariant": { "id": "gid://shopify/ProductVariant/232323", "options": [ { "name": "shoe size", "value": "US 10" } ], "image": { "url": "https://cdn.shopify.com/s/files/...", "altText": "[description of the image]" }, "availableForSale": true } } ] } ] ``` ### Present interactive results with web components Note The iframe URLs shown below are not guaranteed to be stable. You should always use the resource URLs returned as part of MCP responses, rather than constructing the URLs yourself. To display the included UI, you can either fetch the resource URL and render it inline or load it inside of a secure iframe: ```html ``` The web component can be customized with CSS to make it look native in any context. If using an iframe, post a message with theming CSS: ```js const customCss = ` shopify-product-card::part(product-title) { font-weight: 600; } `; iframe.contentWindow.postMessage({ type: "ui-lifecycle-iframe-render-data", payload: { renderData: { customCss } } }) ``` Or if you are using the `` from [MCP-UI](https://mcpui.dev/guide/client/resource-renderer), use the `iframeRenderData` prop: ```js const customCss = ` shopify-product-card::part(product-title) { font-weight: 600; } `; ``` *** ## Add products from any store to a Universal Cart The `update_cart` tool allows your agent to add product variants from any store on the web, including stores not powered by Shopify. The Universal Cart automatically groups items by merchant, maintains buyer information across all carts, calculates combined totals, and generates checkout URLs. Here's an example of how a Universal Cart is structured: ```text 🌐 Universal Cart └── 📦 Cart Group │ └── 🛒 Cart (Merchant A) │ └── 🏷️ Cart Line (Product 1) │ └── 🏷️ Cart Line (Product 2) └── 📦 Cart Group └── 🛒 Cart (Merchant B) └── 🏷️ Cart Line (Product 3) ... ``` * **Universal Cart** contains an array of cart groups and buyer details such as `BuyerIdentity` and `Addresses`. These buyer details are automatically inherited by merchant carts. * **Cart Group** contains a list of carts, their quantities, and total costs. * **Cart** contains the full-fidelity [storefront cart](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage), including cart lines. To add a product from a Shopify merchant, the agent needs to provide the GID of the product variant. For non-Shopify merchants, the agent can provide static details about the store and each line item, allowing the same cart to be used to track products from across the web. ### Create or update a Universal Cart Use `update_cart` with these parameters: * `cart_id`: The ID of the cart to update. Creates a new cart if no ID is provided. * `add_items`: An array of items to add or update, each with a `quantity` and an optional `line_item_id` for existing items. ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "update_cart", "arguments": { "add_items": [ { "product_variant_id": "gid://shopify/ProductVariant/{PRODUCT_ID_1}", "quantity": 1 }, { "product_variant_id": "gid://shopify/ProductVariant/{PRODUCT_ID_2}", "quantity": 1 } ], "buyer_identity": { "email": "andy@wood.com" }, "delivery_addresses_to_add": [ { "delivery_address": { "address_line_1": "11610 Chestnut Street", "city": "Chicago", "country_code": "US", "postal_code": "60618", "state": "IL", "first_name": "Andy", "last_name": "Wood", "phone": "+1234567890" } } ] } } } ``` ### MCP response (Universal Cart) The MCP response contains the serialized JSON cart result with a Universal Cart web component to render a rich and interactive experience: ```json { "id": "gid://shopify/UniversalCart/abc123", "buyerIdentity": { "email": "andy@wood.com" }, "delivery": { "address": { "firstName": "Andy", "lastName": "Wood", "phone": "+13125555555", "address1": "11610 Chestnut Street", "city": "Chicago", "province": "IL", "country": "US", "zip": "60618" } }, "cartGroups": [ { "totalQuantity": 1, "cost": { "totalAmount": { "amount": "20.0", "currencyCode": "USD" } }, "carts": [ { "id": "gid://shopify/Cart/abc123?key=xyz", "checkoutUrl": "https://shop.myshopify.com/cart/c/abc123?key=xyz", "cost": { "totalAmount": { "amount": "20.0", "currencyCode": "USD" } }, "shop": { "id": "gid://shopify/Shop/123", "primaryDomain": { "url": "shop123.myshopify.com" }, "brand": { "logo": { "url": "https://cdn.shopify.com/s/files/1/0000/0000/0000/files/logo.png?format=webp" } } }, "lines": [ { "id": "gid://shopify/CartLine/def456?cart=abc123", "quantity": 1, "merchandise": { "id": "gid://shopify/ProductVariant/{PRODUCT_ID_1}" } } ] } ] }, { "totalQuantity": 1, "cost": { "totalAmount": { "amount": "10.0", "currencyCode": "USD" } }, "carts": [ { "id": "gid://shopify/Cart/ghi789?key=xyz", "checkoutUrl": "https://shop.myshopify.com/cart/c/ghi789?key=xyz", "cost": { "totalAmount": { "amount": "10.0", "currencyCode": "USD" } }, "shop": { "id": "gid://shopify/Shop/456", "primaryDomain": { "url": "shop456.myshopify.com" }, "brand": { "logo": { "url": "https://cdn.shopify.com/s/files/1/0000/0000/0000/files/logo.png?format=webp" } } }, "lines": [ { "id": "gid://shopify/CartLine/jkl012?cart=ghi789", "quantity": 1, "merchandise": { "id": "gid://shopify/ProductVariant/{PRODUCT_ID_2}" } } ] } ] } ] } ``` Here's an example of a Universal Cart rendered with a web component: *** ## Initiate checkout with Checkout Kit Checkout is the final step of a buyer’s journey. It's the most challenging due to merchant customizations combined with jurisdictional compliance and regulations. Shopify manages all of these concerns to help merchants succeed everywhere they sell, using [Checkout Kit](https://www.shopify.com/checkout-kit). Just a few lines of code brings the full power of the best-converting checkout, including all of a merchant’s customizations and business rules. Agents can leverage branding overrides to make the merchant’s checkout look and feel native to their experience on all platforms. All of the merchant customizations powered by [Checkout UI Extensions](https://shopify.dev/docs/api/checkout-ui-extensions) and [Shopify Functions](https://shopify.dev/docs/api/functions) are preserved. Taxes are properly handled. Meeting common compliance requirements, such as GDPR, CCPA, WCAG, and [PCI DSS v4](https://www.shopify.com/ca/partners/blog/checkout-compliance), is made simple. Best of all, using Checkout Kit means you shouldn’t have to worry about the usual marketplace compliance requirements faced by platforms that handle their own payments. ### Platform examples Import the [Checkout Kit React Native SDK](https://shopify.dev/docs/storefronts/mobile/checkout-sheet-kit/react-native) and pass it a checkout URL from Universal Cart. ```js import {useShopifyCheckoutSheet} from '@shopify/checkout-sheet-kit'; function App() { const shopifyCheckout = useShopifyCheckoutSheet(); const handleClick = () => { // Present the checkout shopifyCheckout.present(checkoutUrl); } } ``` ### Advanced checkout customizations Additional functionality will be available soon for select partners and agents, such as: * **Branding controls:** Provide custom colors and typography to match your agent and app user experience. * **Payment tokens:** Provide a pre-authorized payment token to prefill the credit/debit card payment option in a PCI-compliant manner and accelerate the buyer’s checkout. * **Embedded checkout:** Load checkout inline using an iframe for a more deeply embedded experience. *** * [How it works](https://shopify.dev/docs/agents.txt#how-it-works) * [Connect to the MCP server](https://shopify.dev/docs/agents.txt#connect-to-the-mcp-server) * [Find products with the Shopify Catalog](https://shopify.dev/docs/agents.txt#find-products-with-the-shopify-catalog) * [Add products from any store to a Universal Cart](https://shopify.dev/docs/agents.txt#add-products-from-any-store-to-a-universal-cart) * [Initiate checkout with Checkout Kit](https://shopify.dev/docs/agents.txt#initiate-checkout-with-checkout-kit)