--- title: Agentic commerce 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.md --- # Agentic commerce has arrived Build AI agents that can search hundreds of millions of Shopify products, shop across multiple merchants with a single Universal Cart, and deliver seamless, compliant checkout using the Shopify Catalog MCP server and web components. *** Early access Agentic commerce is not generally available, and requires an invitation during the early access period. [Apply now to become an approved agent](https://docs.google.com/forms/d/e/1FAIpQLSekbYOu7R_HTvuo2bX6DUANgu2fRt1ukSc8Ap0y6JuOf7NTaQ/viewform?usp=dialog). ## The agentic commerce stack Bring native shopping into AI conversations, enabling agents to shop across merchants on behalf of a buyer. ![](https://shopify.dev/images/icons/32/number-1.png)![](https://shopify.dev/images/icons/32/number-1-dark.png) #### #### [Shopify Catalog](#shopify-catalog) When buyers ask for products, your agent searches millions of items and displays interactive product cards directly in the chat. ![](https://shopify.dev/images/icons/32/number-2.png)![](https://shopify.dev/images/icons/32/number-2-dark.png) #### #### [Universal Cart](#universal-cart) Buyers can add items from multiple merchants to a single cart, with automatic merchant grouping and unified checkout options. ![](https://shopify.dev/images/icons/32/number-3.png)![](https://shopify.dev/images/icons/32/number-3-dark.png) #### #### [Checkout Kit](#checkout-kit) Buyers complete secure, merchant-branded checkout experiences directly from your agent interface. [![](https://shopify.dev/images/icons/32/youtube.png)![](https://shopify.dev/images/icons/32/youtube-dark.png)](https://www.youtube.com/watch?v=ZPo8n66_6-w) #### [Watch video](https://www.youtube.com/watch?v=ZPo8n66_6-w) [Agentic Commerce: Add Shopping to AI agents](https://www.youtube.com/watch?v=ZPo8n66_6-w) ## Connect to the Catalog 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. *** Caution The bearer token is a private key provided by Shopify to approved agents, used for server-to-server communication. Never commit this key. Restrict usage to environment variables or uncommitted `.env` files. By using the Shopify MCP servers, you agree to the [Shopify API License and Terms of Use](https://www.shopify.com/legal/api-terms). POST ## https\://catalog.shopify.com/api/mcp ```js fetch('https://shopify.dev/service/https://catalog.shopify.com/api/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {YOUR_API_TOKEN}' }, body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/list', id: 1 }) }); ``` ![\[object Object\]](https://shopify.dev/images/icons/32/number-1.png)![\[object Object\]](https://shopify.dev/images/icons/32/number-1-dark.png) #### Shopify Catalog ## 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. In the MCP response `content[].text` is a JSON string to parse, and `content[].resource` contains web components for each product via [MCP UI](https://mcpui.dev/). In this example, a query for “lightweight running shoes” returns an “Awesome Running Shoe - White” that is available in two sizes and sold by two different stores. 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. ### Supported arguments available\_for\_sale•IntDefault: 1 (only available items) Whether to filter products by those available for sale. categories•String 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). For example, for shoes, use: `gid://shopify/TaxonomyCategory/aa-8`. context•String Any additional context on the query that can help future queries surface more relevant results. For example, "The user is trying to find some new running shoes to replace their worn out pair". limit•IntDefault: 10 (max 10) Maximum number of results to return. max\_price•Decimal Maximum price of products to return. min\_price•Decimal Minimum price of products to return. API accepts decimals. query•StringRequired Keyword(s) for search. For example, `Running shoes`. ships\_from•StringDefault: US An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. ships\_to•StringDefault: US An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. ## MCP request: search\_catalog JSON-RPC 2.0 ```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" } } } ``` ## {} Response ```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" } }, ... ] } ``` ```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 } } ] } ] ``` ```json { "type": "resource", "resource": { "uri": "ui://product/gid://shopify/Product/123123", "mimeType": "text/uri-list", "text": "https://cdn.shopify.com/storefront/product-details.component?store_domain=demostore.mock.shop&product_handle=hoodie" } } ``` ##### Response ``` { "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" } }, ... ] } ``` ##### Text ``` [ { "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 } } ] } ] ``` ##### Components ``` { "type": "resource", "resource": { "uri": "ui://product/gid://shopify/Product/123123", "mimeType": "text/uri-list", "text": "https://cdn.shopify.com/storefront/product-details.component?store_domain=demostore.mock.shop&product_handle=hoodie" } } ``` ### Customize components To display the included UI, you can either fetch the resource URL and render it inline or load it inside of a secure iframe. 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. If you are using the `` from MCP-UI, use the `iframeRenderData` prop. ## Customize returned components ```js const customCss = ` shopify-product-card::part(product-title) { font-weight: 600; } `; iframe.contentWindow.postMessage({ type: "ui-lifecycle-iframe-render-data", payload: { renderData: { customCss } } }) ``` ```js const customCss = ` shopify-product-card::part(product-title) { font-weight: 600; } `; ``` ##### postMessage ``` const customCss = ` shopify-product-card::part(product-title) { font-weight: 600; } `; iframe.contentWindow.postMessage({ type: "ui-lifecycle-iframe-render-data", payload: { renderData: { customCss } } }) ``` ##### iframeRenderData ``` const customCss = ` shopify-product-card::part(product-title) { font-weight: 600; } `; ``` Web components ## Interactive results To display the included UI, you can either fetch the resource URL and render it inline or load it inside of a secure iframe. The web component can be customized with CSS to make it look native in any context. ![\[object Object\]](https://shopify.dev/images/icons/32/number-2.png)![\[object Object\]](https://shopify.dev/images/icons/32/number-2-dark.png) #### Universal Cart ## 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. ### Example Universal Cart structure * **Universal Cart**: An array of cart groups and buyer details such as `BuyerIdentity` and `Addresses`. These buyer details are automatically inherited by merchant carts. * **Cart Group**: A list of carts, their quantities, and total costs. * **Cart**: The full-fidelity storefront cart, including cart lines. To add a product from a Shopify merchant, the agent automatically uses the product variant GID from the search results. 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. ```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) ... ``` ### Create or update a Universal Cart Use `update_cart` with these parameters: add\_items•Array An array of items to add or update, each with a `quantity` and an optional `line_item_id` for existing items. cart\_id•StringRequired The ID of the cart to update. Creates cart if no ID is provided. ## MCP request: update\_cart JSON-RPC 2.0 ```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" } } ] } } } ``` ## {} Response ```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}" } } ] } ] } ] } ``` Web components ## Interactive results To display the included UI, you can either fetch the resource URL and render it inline or load it inside of a secure iframe. The web component can be customized with CSS to make it look native in any context. ![\[object Object\]](https://shopify.dev/images/icons/32/number-3.png)![\[object Object\]](https://shopify.dev/images/icons/32/number-3-dark.png) #### Checkout Kit ## Initiate checkout with Checkout Kit Checkout is the final and often hardest step because of merchant customizations and regulations. Shopify's [Checkout Kit](https://www.shopify.com/checkout-kit) handles this for you. With a few lines of code, you get a high-converting checkout that keeps all your existing customizations and business rules. You can apply branding overrides so it looks native on any platform, and all customizations built with [Checkout UI Extensions](https://shopify.dev/docs/api/checkout-ui-extensions) and [Shopify Functions](https://shopify.dev/docs/api/functions) are preserved. Taxes are handled, and common compliance needs (GDPR, CCPA, WCAG, PCI DSS v4) are simplified. [Learn more about Checkout Kit](https://www.shopify.com/checkout-kit) ![Checkout Kit overview](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/agents/checkout-kit-CpXqOyTw.png) ### Platform examples **Android** Import the [Checkout Kit Kotlin SDK](https://shopify.dev/docs/storefronts/mobile/checkout-sheet-kit/android) and pass it a checkout URL from Universal Cart. ## Android ```kotlin import com.shopify.checkoutsheetkit.ShopifyCheckoutSheetKit fun presentCheckout() { val checkoutUrl = cart.checkoutUrl ShopifyCheckoutSheetKit.present(checkoutUrl, context, checkoutEventProcessor) } ``` **iOS** Import the [Checkout Kit Swift SDK](https://shopify.dev/docs/storefronts/mobile/checkout-sheet-kit/swift) and pass it a checkout URL from Universal Cart. ## iOS ```swift import UIKit import ShopifyCheckoutSheetKit class MyViewController: UIViewController { func presentCheckout() { // obtained from Universal Cart let checkoutURL: URL = cart.checkoutUrl ShopifyCheckoutSheetKit.present(checkout: checkoutURL, from: self, delegate: self) } } ``` **React Native** 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. ## React Native ```javascript import {useShopifyCheckoutSheet} from '@shopify/checkout-sheet-kit'; function App() { const shopifyCheckout = useShopifyCheckoutSheet(); const handleClick = () => { // Present the checkout shopifyCheckout.present(checkoutUrl); }; return null; // Add your UI here } ``` **Web** Implement checkout using the [Cart API](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart) and redirect to the checkout URL from Universal Cart. ## Web ```javascript // HTML // // Checkout // JavaScript document.querySelector("a").addEventListener("click", (event) => { event.preventDefault(); const checkout = document.querySelector("shopify-checkout"); checkout.src = event.target.href; checkout.open(); }); ``` 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.