Shopify Agents

https://shopify.dev/docs/agents
Admin
Shopify Agents enables developers to build unified agentic commerce experiences using the Universal...
Tokens:195,402
Snippets:958
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install Express

Source: https://shopify.dev/docs/agents/get-started/monitor-orders

Installs the Express framework, which is required for the webhook server example.

```bash
npm install express
```

--------------------------------

### Run catalog search demo (ucp_demo.js)

Source: https://shopify.dev/docs/agents/get-started/search-catalog

Entry point for the catalog search demo. Imports authentication and search functions, then runs the workflow: get an access token, show the catalog, search products, and display results. Run with `node ucp_demo.js` to start an interactive terminal chat.

```javascript
import { getAccessToken } from './auth.js';
import { searchProducts, displayProducts, showCatalog } from './search.js';


async function main() {
  // 1. Authentication
  const token = await getAccessToken();
  // 2. Search the Catalog
  showCatalog();
  const result = await searchProducts(token);
  if (!result?.products?.length) return;
  displayProducts(result.products);
}


main().catch(err => console.error('Request failed:', err));
```

--------------------------------

### Install Shopify Plugin in VS Code

Source: https://shopify.dev/docs/agents/get-started/quickstart

URL to install the Shopify plugin from source in VS Code. Use this in the Command Palette > Chat: Install Plugin From Source.

```text
https://github.com/Shopify/shopify-ai-toolkit
```

--------------------------------

### lookup_catalog response example

Source: https://shopify.dev/docs/agents/catalog/global-catalog

Example JSON-RPC response from the lookup_catalog tool. Shows product details, variant information, and a not_found message for an ID that could not be resolved.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.catalog.lookup": [{"version": "2026-08-25"}],
          "dev.shopify.catalog.global": [{"version": "2026-08-25"}]
        }
      },
      "products": [
        {
          "id": "gid://shopify/p/7f3a2b8c1d9e",
          "title": "Trail Runner Pro",
          "description": {
            "html": "Lightweight trail running shoe designed for road and light trail."
          },
          "price_range": {
            "min": {"amount": 8999, "currency": "USD"},
            "max": {"amount": 12999, "currency": "USD"}
          },
          "variants": [
            {
              "id": "gid://shopify/ProductVariant/12345678",
              "sku": "TRP-BLK-10",
              "title": "Black / Size 10",
              "price": {"amount": 8999, "currency": "USD"},
              "checkout_url": "https://example-running.myshopify.com/cart/12345678:1",
              "condition": ["new"],
              "eligible": {"native_checkout": true},
              "availability": {"available": true, "status": "in_stock", "running_low": false},
              "requires": {"shipping": true, "selling_plan": false, "components": false},
              "inputs": [
                {"id": "gid://shopify/p/7f3a2b8c1d9e", "match": "featured"}
              ],
              "seller": {
                "name": "Example Running",
                "id": "gid://shopify/Shop/987654321",
                "domain": "example-running.myshopify.com",
                "url": "https://example-running.myshopify.com",
                "links": [
                  {
                    "type": "refund_policy",
                    "url": "https://example-running.myshopify.com/policies/refunds"
                  }
                ]
              }
            }
          ]
        }
      ],
      "messages": [
        {
          "type": "info",
          "code": "not_found",
          "content": "gid://shopify/ProductVariant/87654321"
        }
      ]
    }
  }
}
```

--------------------------------

### create_checkout response example

Source: https://shopify.dev/docs/agents/get-started/checkout

Example response from create_checkout. The status field indicates next steps: incomplete, ready_for_complete, or requires_escalation. For requires_escalation, direct the buyer to continue_url and inspect messages for the reason.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "structuredContent": {
      "id": "gid://shopify/Checkout/abc123?key=xyz789",
      "status": "requires_escalation",
      "messages": [
        { "type": "error", "severity": "requires_buyer_input" },
        { "type": "info", "severity": "requires_buyer_review" }
      ],
      "currency": "USD",
      "line_items": [
        {
          "id": "gid://shopify/CartLine/li_1?cart=abc123",
          "item": {
            "id": "gid://shopify/ProductVariant/11111111111",
            "title": "Organic Cotton Crewneck Sweater",
            "price": 8900
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "amount": 8900, "display_text": "Subtotal" },
            { "type": "total", "amount": 8900, "display_text": "Total" }
          ]
        }
      ],
      "totals": [
        { "type": "subtotal", "amount": 8900, "display_text": "Subtotal" },
        { "type": "total", "amount": 8900, "display_text": "Total" }
      ],
      "expires_at": "2026-02-20T15:17:07Z",
      "continue_url": "https://ecowear-example.myshopify.com/cart/c/abc123?key=xyz789"
    }
  }
}
```

--------------------------------

### Install UCP CLI and Shopify plugin for Cursor

Source: https://shopify.dev/docs/agents

Install the UCP CLI globally and add the Shopify plugin in Cursor Chat. Run the npm command in a terminal and the /add-plugin command in Cursor Chat.

```terminal
npm install -g @shopify/ucp-cli
```

```terminal
/add-plugin shopify
```

--------------------------------

### Antigravity CLI: Install Shopify plugin

Source: https://shopify.dev/docs/agents/get-started/authentication

Installs the Shopify plugin for Antigravity CLI.

```terminal
agy plugin install https://github.com/Shopify/shopify-ai-toolkit
```

--------------------------------

### Get product details with ucp catalog get_product

Source: https://shopify.dev/docs/agents/catalog/global-catalog

Gets full product details for a product GID, with a variant selection specified via the --set flag.

```bash
ucp catalog get_product gid://shopify/Product/67890 \
  --set '/selected/0={"name":"Color","label":"Black"}'
```

--------------------------------

### Install UCP CLI and Shopify plugin for Antigravity CLI

Source: https://shopify.dev/docs/agents

Install the UCP CLI globally and add the Shopify plugin for Antigravity CLI. Run these commands in a terminal.

```terminal
npm install -g @shopify/ucp-cli
```

```terminal
agy plugin install https://github.com/Shopify/shopify-ai-toolkit
```

--------------------------------

### Authentication response example

Source: https://shopify.dev/docs/agents/checkout/mcp

Example response from the authentication endpoint. Contains the access token, granted scopes, and expiration time in seconds.

```json
{
"access_token": "f8563253df0bf277ec9ac6f649fc3f17",
"scope": "read_global_api_catalog_search",
"expires_in": 86399
}
```

--------------------------------

### Create and initialize project directory

Source: https://shopify.dev/docs/agents/get-started/authentication

Creates a 'demo' directory and initializes a Node.js project with npm. This sets up the project for the tutorial.

```bash
mkdir demo && cd demo
npm init -y
```

--------------------------------

### UCP order get response example

Source: https://shopify.dev/docs/agents/get-started/quickstart

Example response from the UCP order get command, showing order details including financial status, fulfillment status, line items, totals, and currency.

```json
{
  "result": {
    "id": "gid://shopify/Order/789",
    "financial_status": "paid",
    "fulfillment_status": "unfulfilled",
    "line_items": [
      {
        "title": "Sony WH-CH520 Wireless Bluetooth Headphones",
        "quantity": 1,
        "subtotal": 5999
      }
    ],
    "totals": [
      {"type": "total", "display_text": "Total", "amount": 5999}
    ],
    "currency": "USD"
  }
}
```

--------------------------------

### Get cart permalink from Global Catalog response

Source: https://shopify.dev/docs/agents/carts-and-checkout

Example response from the Global Catalog's get_product tool, showing a variant's checkout_url that can be used as a cart permalink.

```json
{
  "product": {
    "title": "Organic Cotton Crewneck Sweater",
    "variants": [
      {
        "id": "gid://shopify/ProductVariant/11111111111",
        "checkout_url": "https://ecowear-example.myshopify.com/cart/11111111111:1?payment=shop_pay"
      }
    ]
  }
}
```

--------------------------------

### Run ucp_demo.js

Source: https://shopify.dev/docs/agents/get-started/authentication

Runs the main tutorial script from the terminal to verify credentials work. Expected output shows the authentication step, the scopes (read_global_api_catalog_search), and the token expiration time.

```bash
node ucp_demo.js
```

--------------------------------

### Create ucp_demo.js main script

Source: https://shopify.dev/docs/agents/get-started/authentication

Main entry point for the tutorial. Imports getAccessToken from './auth.js' and calls it inside an async main function, logging any errors to the console. You will update this file in each tutorial step.

```javascript
import { getAccessToken } from './auth.js';


async function main() {
  // 1. Authentication
  const token = await getAccessToken();
}


main().catch(err => console.error('Request failed:', err));
```

--------------------------------

### get_product tool response

Source: https://shopify.dev/docs/agents/catalog/storefront-catalog

Example JSON-RPC response from the get_product tool, showing the product details, options, variants, and rating.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.catalog.lookup": [
            {"version": "2026-08-25"}
          ]
        }
      },
      "product": {
        "id": "gid://shopify/Product/123",
        "handle": "runner-pro",
        "title": "Runner Pro",
        "description": {
          "html": "Lightweight running shoes with responsive cushioning."
        },
        "url": "https://business.example.com/products/runner-pro",
        "price_range": {
          "min": {"amount": 12000, "currency": "USD"},
          "max": {"amount": 15000, "currency": "USD"}
        },
        "media": [
          {
            "type": "image",
            "url": "https://cdn.example.com/products/runner-pro-blue.jpg",
            "alt_text": "Runner Pro in Blue"
          }
        ],
        "options": [
          {
            "name": "Color",
            "values": [
              {"label": "Blue", "available": true, "exists": true},
              {"label": "Red", "available": true, "exists": true},
              {"label": "Green", "available": false, "exists": true}
            ]
          },
          {
            "name": "Size",
            "values": [
              {"label": "8", "available": true, "exists": true},
              {"label": "9", "available": true, "exists": true},
              {"label": "10", "available": true, "exists": true},
              {"label": "11", "available": false, "exists": false},
              {"label": "12", "available": true, "exists": true}
            ]
          }
        ],
        "selected": [
          {"name": "Color", "label": "Blue"}
        ],
        "variants": [
          {
            "id": "gid://shopify/ProductVariant/1001",
            "sku": "BRP-BLU-10",
            "title": "Blue, Size 10",
            "description": {"plain": "Blue, Size 10"},
            "price": {"amount": 12000, "currency": "USD"},
            "availability": {"available": true},
            "options": [
              {"name": "Color", "label": "Blue"},
              {"name": "Size", "label": "10"}
            ]
          },
          {
            "id": "gid://shopify/ProductVariant/1002",
            "sku": "BRP-BLU-12",
            "title": "Blue, Size 12",
            "description": {"plain": "Blue, Size 12"},
            "price": {"amount": 15000, "currency": "USD"},
            "availability": {"available": true},
            "options": [
              {"name": "Color", "label": "Blue"},
              {"name": "Size", "label": "12"}
            ]
          }
        ],
        "rating": {
          "value": 4.5,
          "scale_max": 5,
          "count": 128
        }
      }
    }
  }
}
```

--------------------------------

### Codex: Install Shopify plugin

Source: https://shopify.dev/docs/agents/get-started/authentication

Installs the Shopify plugin for Codex.

```terminal
codex plugin add shopify@openai-curated
```

--------------------------------

### Install UCP CLI and Shopify plugin for Codex

Source: https://shopify.dev/docs/agents/get-started/quickstart

Install the UCP CLI globally and then install the Shopify plugin for Codex. Requires Node.js 18 or higher and a supported AI tool.

```terminal
npm install -g @shopify/ucp-cli
```

```terminal
codex plugin add shopify@openai-curated
```

--------------------------------

### JSON-RPC request for search_shop_policies_and_faqs

Source: https://shopify.dev/docs/agents/catalog/policy-and-faqs-tool

Example JSON-RPC request to call the `search_shop_policies_and_faqs` tool. The `query` parameter is required; `context` is optional.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_shop_policies_and_faqs",
    "arguments": {
      "query": "What is your return policy for sale items?",
      "context": "Customer is looking at discounted winter jackets"
    }
  }
}
```

--------------------------------

### Install UCP CLI and Shopify plugin for Claude Code

Source: https://shopify.dev/docs/agents/get-started/quickstart

Install the UCP CLI globally and then install the Shopify AI Toolkit plugin for Claude Code. Requires Node.js 18 or higher and a supported AI tool.

```terminal
npm install -g @shopify/ucp-cli
```

```terminal
claude plugin install shopify-ai-toolkit@claude-plugins-official
```

--------------------------------

### Claude Code: Install Shopify plugin

Source: https://shopify.dev/docs/agents/get-started/authentication

Installs the Shopify plugin in Claude Code after adding the marketplace.

```terminal
/plugin install shopify-plugin@shopify-ai-toolkit
```

--------------------------------

### Response from search_catalog tool

Source: https://shopify.dev/docs/agents/catalog/storefront-catalog

Example JSON-RPC response from the search_catalog tool, containing structured content with product details, pagination, and capabilities.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-08-25",
        "capabilities": {
          "dev.ucp.shopping.catalog.search": [
            {"version": "2026-08-25"}
          ]
        }
      },
      "products": [
        {
          "id": "gid://shopify/Product/1001",
          "handle": "fair-trade-organic-whole-bean",
          "title": "Fair Trade Organic Whole Bean Coffee",
          "description": {
            "html": "USDA organic whole beans; Fair Trade Certified; medium roast. Roasted in small batches."
          },
          "url": "https://business.example.com/products/fair-trade-organic-whole-bean",
          "categories": [
            {"value": "413", "taxonomy": "google_product_category"},
            {"value": "fb-1-2-3", "taxonomy": "shopify"},
            {"value": "Food, Beverages & Tobacco > Beverages > Coffee", "taxonomy": "merchant"}
          ],
          "price_range": {
            "min": {"amount": 1899, "currency": "USD"},
            "max": {"amount": 3499, "currency": "USD"}
          },
          "media": [
            {
              "type": "image",
              "url": "https://cdn.example.com/products/fair-trade-organic-whole-bean.jpg",
              "alt_text": "Bag of fair trade organic whole bean coffee"
            }
          ],
          "options": [
            {
              "name": "Bag size",
              "values": [
                {"label": "12 oz"},
                {"label": "2 lb"},
                {"label": "5 lb"}
              ]
            }
          ],
          "variants": [
            {
              "id": "gid://shopify/ProductVariant/2001",
              "sku": "FT-ORG-WB-12OZ",
              "title": "12 oz",
              "description": {"plain": "12 oz bag — fair trade organic whole bean"},
              "price": {"amount": 1899, "currency": "USD"},
              "availability": {"available": true},
              "options": [{"name": "Bag size", "label": "12 oz"}],
              "tags": ["organic", "fair trade", "whole bean", "coffee"]
            }
          ],
          "rating": {"value": 4.7, "scale_max": 5, "count": 312},
          "metadata": {
            "certifications": ["USDA Organic", "Fair Trade Certified"]
          }
        }
      ],
      "pagination": {
        "cursor": "eyJwYWdlIjoxfQ==",
        "has_next_page": true,
        "total_count": 24
      }
    }
  }
}
```

--------------------------------

### cancel_checkout response example

Source: https://shopify.dev/docs/agents/get-started/checkout

Example response from the cancel_checkout tool call. The structuredContent contains the checkout ID and status 'canceled'.

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "structuredContent": {
      "id": "gid://shopify/Checkout/abc123?key=xyz789",
      "status": "canceled"
    }
  }
}
```

--------------------------------

### product.js: Fetch product details and select a variant

Source: https://shopify.dev/docs/agents/get-started/search-catalog

Create product.js to fetch product details via the get_product tool, display them, and guide the buyer through variant selection. It uses the CATALOG_URL and prompt from the search step, and returns a variant with its checkout_url when the buyer confirms a selection.

```javascript
import { prompt } from './utils.js';
import { CATALOG_URL } from './search.js';

async function getProductDetails(token, productId, selected = []) {
  const res = await fetch(CATALOG_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'tools/call',
      id: 2,
      params: {
        name: 'get_product',
        arguments: {
          meta: {
            'ucp-agent': {
              profile: 'https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json'
            }
          },
          catalog: {
            id: productId,
            ...(selected.length ? { selected } : {})
          }
        }
      }
    })
  });
  const data = await res.json();
  return data.result?.structuredContent ?? null;
}

function displayProduct(product) {
  const featuredVariant = product.variants?.[0];
  const price = featuredVariant ? `$${(featuredVariant.price.amount / 100).toFixed(2)}` : '';
  const sellerName = featuredVariant?.seller?.name ?? '';
  const variantTitle = featuredVariant?.title ?? '';
  console.log('\n── 3. Product Details ─────────────────────────────\n');
  console.log(`  ${product.title}${variantTitle ? ` - ${variantTitle}` : ''}`);
  console.log(`  ${[price, sellerName].filter(Boolean).join('  ·  ')}\n`);
  if (product.description?.html) console.log(`  ${product.description.html}\n`);
}

async function pickVariant(token, productId, product) {
  const selected = Object.fromEntries(
    (product.selected ?? []).map(s => [s.name, s.label])
  );

  if (product.options?.length) while (true) {
    const optionMap = [];
    console.log('\n  Options:');
    product.options.forEach(opt => {
      const lines = opt.values.map(v => {
        const n = optionMap.length + 1;
        const marker = selected[opt.name] === v.label ? '●' : '○';
        optionMap.push({ optName: opt.name, label: v.label });
        return `    [${n}] ${marker} ${v.label}${v.available === false ? ' (unavailable)' : ''}`;
      });
      console.log(`\n  ${opt.name}:`);
      lines.forEach(l => console.log(l));
    });

    const selectedDesc = product.options.map(o => selected[o.name]).join(' / ');
    console.log(`\n  \x1b[1mSelected: ${selectedDesc}\x1b[0m`);
    console.log('\n  [s] Select this variant  [number] Pick an option  [b] Back to results');
    const action = await prompt('\n  > ');
    const trimmed = action.trim();

    if (trimmed === 'b') return null;
    if (trimmed === 's') {
      const selectedArr = Object.entries(selected).map(([name, label]) => ({ name, label }));
      const details = await getProductDetails(token, productId, selectedArr);
      const variant = details?.product?.variants?.[0];
      return variant ? { variantId: variant.id, checkout_url: variant.checkout_url } : null;
    }

    const chosen = optionMap[parseInt(trimmed) - 1];
    if (chosen) selected[chosen.optName] = chosen.label;
  }

  const variant = product.variants?.[0];
  return variant ? { variantId: variant.id, checkout_url: variant.checkout_url } : null;
}

export async function selectProduct(token, products) {
  const pick = await prompt(`\x1b[1m  Lookup details on a result [1-${products.length}]:\x1b[0m  `);
  const index = parseInt(pick) - 1;
  const selectedProduct = products[index];
  const details = await getProductDetails(token, selectedProduct.id);
  const product = details?.product;
  if (!product) return null;
  displayProduct(product);
  const variant = await pickVariant(token, selectedProduct.id, product);
  return variant;
}

```

--------------------------------

### Install UCP CLI

Source: https://shopify.dev/docs/agents/get-started/authentication

Installs the UCP CLI globally. Required for all AI tools before using the Shopify AI Toolkit plugin.

```terminal
npm install -g @shopify/ucp-cli
```

--------------------------------

### JSON example: video with two renditions and 3D model with GLB and USDZ encodings

Source: https://shopify.dev/docs/agents/catalog/global-catalog-extension

Shows the media array structure for a video with two sources (mp4 and m3u8) and a 3D model with GLB and USDZ sources. Includes fields like type, url, name, alt_text, duration, preview, and sources. Use this as a reference for constructing media arrays in the draft version.

```json
{
  "media": [
    {
      "type": "video",
      "url": "https://cdn.example.com/products/runner-pro-demo-720p.mp4",
      "name": "Runner Pro flex demo",
      "alt_text": "Runner Pro shoe flexing to show sole cushioning.",
      "duration": 24,
      "preview": {
        "url": "https://cdn.example.com/products/runner-pro-demo-poster.jpg",
        "width": 1280,
        "height": 720
      },
      "sources": [
        {
          "url": "https://cdn.example.com/products/runner-pro-demo-720p.mp4",
          "mime_type": "video/mp4",
          "format": "mp4",
          "width": 1280,
          "height": 720,
          "filesize": 4200000
        },
        {
          "url": "https://cdn.example.com/products/runner-pro-demo.m3u8",
          "mime_type": "application/vnd.apple.mpegurl",
          "format": "m3u8"
        }
      ]
    },
    {
      "type": "model_3d",
      "url": "https://cdn.example.com/products/runner-pro.glb",
      "name": "Runner Pro 3D model",
      "alt_text": "Rotatable 3D model of the Runner Pro shoe.",
      "preview": {
        "url": "https://cdn.example.com/products/runner-pro-3d-poster.jpg"
      },
      "sources": [
        {
          "url": "https://cdn.example.com/products/runner-pro.glb",
          "mime_type": "model/gltf-binary",
          "format": "glb",
          "filesize": 4200000
        },
        {
          "url": "https://cdn.example.com/products/runner-pro.usdz",
          "mime_type": "model/vnd.usdz+zip",
          "format": "usdz",
          "filesize": 5100000
        }
      ]
    }
  ]
}
```
Tokens:
Raw