Skip to main content

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.

Anchor to The agentic commerce stackThe agentic commerce stack

Bring native shopping into AI conversations, enabling agents to shop across merchants on behalf of a buyer.

Shopify Catalog

When buyers ask for products, your agent searches millions of items and displays interactive product cards directly in the chat.

Universal Cart

Buyers can add items from multiple merchants to a single cart, with automatic merchant grouping and unified checkout options.

Checkout Kit

Buyers complete secure, merchant-branded checkout experiences directly from your agent interface.

Watch video

Agentic Commerce: Add Shopping to AI agents

Anchor to Connect to the Catalog MCP serverConnect to the Catalog MCP server

The Shopify Catalog MCP server is an authenticated endpoint that requires an authorization bearer token. 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.

POST

https://catalog.shopify.com/api/mcp

fetch('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
})
});

Shopify Catalog

Anchor to Find products with the Shopify CatalogFind 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. 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 for a deep-dive on MCP UI.

Anchor to Supported argumentsSupported 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 and raw category list.

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 country code.

ships_to•StringDefault: US

An ISO 3166 country code.

MCP request: search_catalog

JSON-RPC 2.0
{
"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

{
"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"
}
},
...
]
}
[
{
"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
}
}
]
}
]
{
"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"
}
}

Anchor to Customize componentsCustomize 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 <UIResourceRenderer /> from MCP-UI, use the iframeRenderData prop.

Customize returned components

const customCss = `
shopify-product-card::part(product-title) {
font-weight: 600;
}
`;

iframe.contentWindow.postMessage({
type: "ui-lifecycle-iframe-render-data",
payload: {
renderData: {
customCss
}
}
})
const customCss = `
shopify-product-card::part(product-title) {
font-weight: 600;
}
`;

<UIResourceRenderer
resource={resource}
htmlProps={{
iframeRenderData: {customCss},
}}
/>
Web components

Anchor to Interactive resultsInteractive 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.

Universal Cart

Anchor to Add products from any store to a Universal CartAdd 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.

Anchor to Example Universal Cart structureExample 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.

🌐 Universal Cart
└── 📦 Cart Group
│ └── 🛒 Cart (Merchant A)
│ └── 🏷️ Cart Line (Product 1)
│ └── 🏷️ Cart Line (Product 2)
└── 📦 Cart Group
└── 🛒 Cart (Merchant B)
└── 🏷️ Cart Line (Product 3)
...

Anchor to Create or update a Universal CartCreate 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
{
"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

{
"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

Anchor to Interactive resultsInteractive 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.

Checkout Kit

Anchor to Initiate checkout with Checkout KitInitiate checkout with Checkout Kit

Checkout is the final and often hardest step because of merchant customizations and regulations. Shopify's 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 and Shopify Functions are preserved. Taxes are handled, and common compliance needs (GDPR, CCPA, WCAG, PCI DSS v4) are simplified.

Learn more about Checkout Kit

Checkout Kit overview

Anchor to Platform examplesPlatform examples

Android

Import the Checkout Kit Kotlin SDK and pass it a checkout URL from Universal Cart.

Android

import com.shopify.checkoutsheetkit.ShopifyCheckoutSheetKit

fun presentCheckout() {
val checkoutUrl = cart.checkoutUrl
ShopifyCheckoutSheetKit.present(checkoutUrl, context, checkoutEventProcessor)
}

iOS

Import the Checkout Kit Swift SDK and pass it a checkout URL from Universal Cart.

iOS

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 and pass it a checkout URL from Universal Cart.

React Native

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 and redirect to the checkout URL from Universal Cart.

Web

// HTML
// <shopify-checkout></shopify-checkout>
// <a href="https://shop.myshopify.com/cart/43696905224214:1">Checkout</a>

// 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.