Skip to main content

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, and more. And because Shopify handles checkout for you, you shouldn't have to worry about the usual marketplace compliance requirements faced by platforms that handle their own payments.

Early access

Sign up here for early access to apply and become an approved agent.

Anchor to How it worksHow it works

The Shopify Catalog MCP server lets your agent shop across merchants on behalf of a buyer:

  1. 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: 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: 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.

Anchor to Connect to the MCP serverConnect to the 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.

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.

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.

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.

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

Anchor to Supported argumentsSupported arguments

FieldDescriptionTypeExample Value
query (required)Keyword(s) for searchStringRunning Shoes
limitMaximum number of results to return (defaults to 10, max of 10)Integer (1-10)5
min_priceMinimum price of products to return. API accepts decimals.Decimal (currency determined by ships_to)10
max_priceMaximum price of products to return. API accepts decimals.Decimal (currency determined by ships_to)100
categoriesComma-delimited list of global IDs for taxonomy categories. Refer to the Shopify Standard Product Taxonomy and raw category list.StringFor example, for shoes, use: gid://shopify/TaxonomyCategory/aa-8
ships_toA single ISO 3166 code that country code is extracted from.StringUS (default), CA
ships_fromA single ISO 3166 code that country code is extracted from.StringUS (default), CA
available_for_saleWhether to filter available for sale.Int (0,1)0 (false or include not available products), 1 (true or exclude not available products, default)
contextAny additional context on the query that can help us surface more relevant results.StringThe user is trying to find some new running shoes to replace their worn out pair.

Anchor to MCP responseMCP response

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. These can optionally be used to render rich and interactive product cards.

Tip

See our blog post on Breaking the text wall for a deep-dive on MCP UI.

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

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

Anchor to Present interactive results with web componentsPresent 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:

<iframe
src="https://cdn.shopify.com/storefront/product-details.component?store_domain=demostore.mock.shop&product_handle=hoodie">
</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:

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 <UIResourceRenderer /> from MCP-UI, use the iframeRenderData prop:

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

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

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.

Here's an example of how a Universal Cart is structured:

🌐 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 and their quantities and total costs.
  • Cart contains the full-fidelity storefront cart, including cart lines.

To add a product from a Shopify merchant the agent only 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.

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

Anchor to MCP responseMCP response

The MCP response contains the serialized JSON cart result with a Universal Cart web component to render a rich and interactive experience:

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

Anchor to Initiate checkout with Checkout KitInitiate 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. 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 and Shopify Functions are preserved. Taxes are properly handled. Meeting common compliance requirements, such as GDPR, CCPA, WCAG, and PCI DSS v4, 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.

Anchor to Platform examplesPlatform examples

Import the checkout web component and pass it a checkout URL from Universal Cart. Review the web component documentation for callbacks, styling, and other customizations.

<script src="https://cdn.shopify.com/storefront/web-components.js"></script>

<shopify-checkout></shopify-checkout>

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

<script>
document.querySelector("a").addEventListener("click", (event) => {
event.preventDefault();

const checkout = document.querySelector("shopify-checkout");
checkout.src = event.target.href;
checkout.open();
});
</script>

Anchor to Advanced checkout customizationsAdvanced 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.
Was this page helpful?