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:

• Check which UCP profile the CLI uses.
• 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 22.19.0 or higher.
• A supported AI tool: Claude Code, Codex, Antigravity CLI, Cursor, 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: Check your profileStep 2: Check your profile

The CLI uses a profile to identify your agent on every merchant-scoped request. By default, the CLI uses the Shopify-managed profile. You don't need to set anything up. To check which profile is active, run ucp profile show:

The ucp profile show command displays the active profile, or a local profile that you name. To list the Shopify-managed profile and your local profiles, with the active profile marked, run ucp profile list.

To pin your agent to a specific UCP release, run ucp profile init --name {profile_name} --activate. This command creates a profile that's pinned to one UCP release. Without --activate, the CLI creates the profile but keeps your current selection. The CLI stores the profile document at ~/.ucp/profiles/{profile_name}/profile.json. To advertise a custom capability set, also pass --profile-url with an HTTPS URL that you control, and publish the profile document at that URL.

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",
          "price": 5999
        },
        "quantity": 1,
        "totals": [
          {"type": "subtotal", "display_text": "Subtotal", "amount": 5999},
          {"type": "total", "display_text": "Total", "amount": 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 cart ID returned in result.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",
      "label": "#1001",
      "permalink_url": "https://audiogear.example.com/orders/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 the ID that ucp checkout complete returned in result.order.id:

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

{
  "result": {
    "id": "gid://shopify/Order/789",
    "label": "#1001",
    "checkout_id": "gid://shopify/Checkout/def456",
    "permalink_url": "https://audiogear.example.com/orders/789",
    "currency": "USD",
    "line_items": [
      {
        "id": "gid://shopify/LineItem/456",
        "item": {
          "id": "gid://shopify/ProductVariant/41293818167385",
          "title": "Sony WH-CH520 Wireless Bluetooth Headphones",
          "price": 5999
        },
        "quantity": {"original": 1, "total": 1, "fulfilled": 0},
        "totals": [
          {"type": "subtotal", "display_text": "subtotal", "amount": 5999},
          {"type": "total", "display_text": "total", "amount": 5999}
        ],
        "status": "processing"
      }
    ],
    "fulfillment": {"expectations": [], "events": []},
    "totals": [
      {"type": "subtotal", "display_text": "subtotal", "amount": 5999},
      {"type": "total", "display_text": "total", "amount": 5999}
    ]
  }
}

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.