---
title: Quickstart
description: Run the full agentic commerce flow with the UCP CLI in about five minutes.
source_url:
  html: 'https://shopify.dev/docs/agents/get-started/quickstart'
  md: 'https://shopify.dev/docs/agents/get-started/quickstart.md'
---

# 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](https://shopify.dev/docs/agents/get-started/authentication).

***

## What 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.

***

## Requirements

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

***

## Step 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.

#### Claude Code

## Terminal: Install the UCP CLI

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

## Claude Code: Enable the Shopify marketplace

```terminal
/plugin marketplace add Shopify/shopify-ai-toolkit
```

## Claude Code: Install the plugin

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

#### Cursor

## Terminal: Install the UCP CLI

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

## Cursor Chat: Add the plugin

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

#### Gemini CLI

## Terminal: Install the UCP CLI

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

## Terminal: Install the Shopify extension

```terminal
gemini extensions install https://github.com/Shopify/shopify-ai-toolkit
```

#### VS Code

## Terminal: Install the UCP CLI

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

## Command Palette > Chat: Install Plugin From Source

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

***

## Step 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.

##### bash

```bash
ucp profile init --name agent
```

##### {} Response

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

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

***

## Step 3: Search the Catalog

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

##### bash

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

##### {} Response

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

***

## Step 4: Build a cart

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

##### bash

```bash
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
```

##### {} Response

```json
{
  "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.

***

## Step 5: Convert to checkout

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

##### bash

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

##### {} Response

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

##### bash

```bash
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}
```

##### {} Response

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

## Terminal

```bash
export UCP_ON_ESCALATION='jq -r .url | xargs open'
```

***

## Step 6: Track the order

After checkout, look up the order by ID:

##### bash

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

##### {} Response

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

***

## Next steps

[Build it from scratch\
\
](https://shopify.dev/docs/agents/get-started/authentication)

[Hand-roll the same flow against Shopify's MCP servers to see what the CLI does under the hood.](https://shopify.dev/docs/agents/get-started/authentication)

[UCP CLI reference\
\
](https://github.com/Shopify/ucp-cli)

[Full command reference and advanced options.](https://github.com/Shopify/ucp-cli)

***