Quickstart

This quickstart runs the full agentic commerce flow with the UCP CLI, from product discovery to order tracking, in about five minutes. For a hand-rolled walkthrough that builds the same flow against Shopify's MCP servers directly, see the six-part tutorial series.

Anchor to What you'll learnWhat you'll learn

In this quickstart, you'll learn to:

• Initialize a local UCP profile.
• Search the global Catalog for products.
• Build a cart at a specific merchant.
• Convert that cart into a checkout.
• Track an order after purchase.

Anchor to RequirementsRequirements

• Node.js 18 or higher.
• A supported AI tool: Claude Code, Cursor, Gemini CLI, or VS Code.

Anchor to Step 1: Install the UCP CLI and Shopify AI ToolkitStep 1: Install the UCP CLI and Shopify AI Toolkit

Install the UCP CLI for your terminal and the Shopify AI Toolkit plugin for your AI provider.

Anchor to Step 2: Initialize your profileStep 2: Initialize your profile

The CLI uses a local profile to identify your agent on every merchant-scoped request. Initialize it once and the CLI reuses it for every operation.

ucp profile init --name agent

{
  "profile": "agent",
  "path": "~/.ucp/profiles/agent.yaml",
  "active": true
}

Run ucp doctor at any time to verify your setup is healthy.

Anchor to Step 3: Search the CatalogStep 3: Search the Catalog

The global Catalog searches across millions of products from Shopify-powered merchants. Pass a natural-language query and optional context:

ucp catalog search \
  --set /query='wireless headphones under $100' \
  --set /context/address_country=US \
  --view :compact \
  --format md

| title                                       | price | currency | variant                                       | buy                                                       |
|---------------------------------------------|-------|----------|-----------------------------------------------|-----------------------------------------------------------|
| Sony WH-CH520 Wireless Bluetooth Headphones | 5999  | USD      | gid://shopify/ProductVariant/41293818167385   | https://audiogear.example.com/cart/41293818167385:1       |
| JBL Tune 510BT Wireless On-Ear Headphones   | 4999  | USD      | gid://shopify/ProductVariant/49158410436908   | https://soundsource.example.com/cart/49158410436908:1     |

Each result names the merchant it came from in seller.domain. Pick a product and copy its variant id and the merchant URL for the next step.

Anchor to Step 4: Build a cartStep 4: Build a cart

Pass the variant id and the merchant URL to ucp cart create:

ucp cart create --business https://{merchant-domain} \
  --set /line_items/0/item/id='{variant_id}' \
  --set /line_items/0/quantity=1 \
  --set /context/address_country=US

{
  "result": {
    "id": "gid://shopify/Cart/abc123",
    "currency": "USD",
    "line_items": [
      {
        "id": "gid://shopify/CartLine/xyz789",
        "item": {
          "id": "gid://shopify/ProductVariant/41293818167385",
          "title": "Sony WH-CH520 Wireless Bluetooth Headphones"
        },
        "quantity": 1,
        "subtotal": 5999
      }
    ],
    "totals": [
      {"type": "subtotal", "display_text": "Subtotal", "amount": 5999},
      {"type": "total", "display_text": "Total", "amount": 5999}
    ],
    "continue_url": "https://audiogear.example.com/cart/c/abc123"
  }
}

The merchant returns a cart with confirmed pricing and a continue_url the buyer can use to finish in their browser. Save the returned cart.id for the next step.

Anchor to Step 5: Convert to checkoutStep 5: Convert to checkout

When the buyer commits, convert the cart into a checkout:

ucp checkout create --business https://{merchant-domain} \
  --input '{"cart_id":"{cart_id}","line_items":[]}'

{
  "result": {
    "id": "gid://shopify/Checkout/def456",
    "status": "incomplete",
    "continue_url": "https://audiogear.example.com/checkouts/def456"
  }
}

Inspect what the merchant expects next (fulfillment address, shipping selection) with --input-schema, then update and complete:

ucp checkout update {checkout_id} --input-schema --business https://{merchant-domain}
ucp checkout update {checkout_id} --business https://{merchant-domain} --input '...'
ucp checkout complete {checkout_id} --business https://{merchant-domain}

{
  "result": {
    "id": "gid://shopify/Checkout/def456",
    "status": "completed",
    "order_id": "gid://shopify/Order/789"
  }
}

If the merchant requires buyer review, the CLI can hand off to the browser. Set an escalation hook before running checkout:

Anchor to Step 6: Track the orderStep 6: Track the order

After checkout, look up the order by ID:

ucp order get {order_id} --business https://{merchant-domain}

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

Anchor to Next stepsNext steps

Build it from scratch

Hand-roll the same flow against Shopify's MCP servers to see what the CLI does under the hood.

UCP CLI reference

Full command reference and advanced options.