> ## Documentation Index
> Fetch the complete documentation index at: https://agentmall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent searches and buys

> End-to-end example — connect, search Walmart, add to cart, and check out.

![End-to-end flow: search, cart, checkout, confirmed](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/agent-buys.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=ce46611adc4d7915e8b6abfd648cf0a7)

An end-to-end example: your agent connects, searches Walmart for batteries, adds them to a cart, and checks out.

Every call below is an MCP tool call. The same operations work on [REST](https://agentmall.mintlify.site/surfaces/rest-api.md).

## 1. Create a cart

```json theme={null}
{
  "shopper_id": "shp_demo",
  "merchant_id": "mrc_walmart",
  "account": "platform"
}
```

`create_cart` returns an empty cart. The `id` is used by every later call.

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "merchant_id": "mrc_walmart",
  "currency": "USD",
  "line_items": [],
  "totals": { "subtotal": 0, "total": 0 }
}
```

`account: "platform"` uses the signed-in AgentMall Walmart account and clears its shared cart. Omit `account` for a shopper browser, then call `sign_in` with encrypted credentials.

## 2. Search

```json theme={null}
{
  "merchant_id": "mrc_walmart",
  "query": "AA batteries"
}
```

`search_catalog` returns up to 10 products. Prices are integer minor units (cents for USD).

```json theme={null}
{
  "products": [
    {
      "id": "27574659",
      "title": "Energizer MAX AA Batteries, 24 Pack",
      "brand": "Energizer",
      "url": "https://www.walmart.com/ip/27574659",
      "price": 1697,
      "currency": "USD",
      "availability": "in_stock"
    },
    {
      "id": "585061508",
      "title": "Duracell Coppertop AA Batteries, 28 Pack",
      "brand": "Duracell",
      "url": "https://www.walmart.com/ip/585061508",
      "price": 2197,
      "currency": "USD",
      "availability": "in_stock"
    }
  ],
  "source": "oxylabs",
  "relevance": "ok"
}
```

**Check the title.** Search results are real Walmart listings. Confirm the product matches what the shopper asked for before adding it to the cart.

## 3. Add to cart

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "line_items": [
    {
      "item": { "id": "27574659", "url": "https://www.walmart.com/ip/27574659" },
      "quantity": 1
    }
  ]
}
```

`update_cart` replaces the cart contents. The response includes the live line items and totals from the merchant.

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "currency": "USD",
  "line_items": [
    {
      "id": "27574659",
      "item": {
        "id": "27574659",
        "title": "Energizer MAX AA Batteries, 24 Pack",
        "price": 1697,
        "url": "https://www.walmart.com/ip/27574659"
      },
      "quantity": 1,
      "totals": { "subtotal": 1697, "total": 1697 }
    }
  ],
  "totals": { "subtotal": 1697, "total": 1697 }
}
```

The `url` must already point to the chosen size or colour. If the product has options, call `get_product` first to get the `variants` list, then use the variant's `id` and `url`.

## 4. Open checkout

```json theme={null}
{
  "cart_id": "ses_01JB7PK8M2AN4R8D091CD"
}
```

`create_checkout` opens the checkout page and reads it. Nothing is placed.

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "status": "incomplete",
  "line_items": [
    { "itemId": "27574659", "quantity": 1, "linePrice": { "amountMinor": 1697, "currency": "USD" } }
  ],
  "totals": { "subtotal": 1697, "total": 1697 },
  "fulfillment": {
    "methods": [
      { "id": "shipping_standard", "kind": "shipping", "label": "Standard shipping" },
      { "id": "pickup_store_3795", "kind": "pickup", "label": "Pickup at Supercenter #3795" }
    ]
  },
  "review_hash": "a1b2c3d4e5f6..."
}
```

Tax and total are estimates until an address is set.

## 5. Set address and shipping

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "fulfillment": {
    "address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "street_address": "123 Main St",
      "address_locality": "Austin",
      "address_region": "TX",
      "postal_code": "78701",
      "address_country": "US"
    },
    "method": { "id": "shipping_standard", "kind": "shipping", "label": "Standard shipping" }
  }
}
```

`update_checkout` writes the address and selects shipping. The response includes updated totals with tax.

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "status": "incomplete",
  "totals": { "subtotal": 1697, "tax": 140, "total": 1837 },
  "review_hash": "b2c3d4e5f6a1..."
}
```

Show these totals to the shopper before asking for a card.

## 6. Add payment

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "payment": {
    "instruments": [
      {
        "id": "card_1",
        "handler_id": "dev.agentmall.card",
        "type": "card",
        "selected": true,
        "credential": { "type": "ciphertext", "value": "ev:AAAD..." }
      }
    ]
  }
}
```

The card value is Evervault `ev:` ciphertext, collected through the console's card collection page. Never send a raw card number.

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "status": "ready",
  "totals": { "subtotal": 1697, "tax": 140, "total": 1837 },
  "review_hash": "c3d4e5f6a1b2..."
}
```

## 7. Place the order

Show the review to the shopper. When they approve:

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "review_hash": "c3d4e5f6a1b2...",
  "total_minor": 1837
}
```

`complete_checkout` places the order. One approval, one merchant commit.

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "status": "completed",
  "order": { "id": "ord_01JB7QR9N3BP5S2E082AB" },
  "test": false
}
```

The session ends. The AgentMall fee (\$0.50) is charged to your organization.

## 8. Verify the order

```json theme={null}
{
  "id": "ord_01JB7QR9N3BP5S2E082AB"
}
```

`get_order` reads the order. No session needed.

```json theme={null}
{
  "id": "ord_01JB7QR9N3BP5S2E082AB",
  "checkout_id": "ses_01JB7PK8M2AN4R8D091CD",
  "merchant_id": "mrc_walmart",
  "status": "completed",
  "merchant_status": "Processing",
  "currency": "USD",
  "totals": { "subtotal": 1697, "tax": 140, "total": 1837 },
  "permalink_url": "https://www.walmart.com/orders/2000123-45678901",
  "test": false
}
```

## What to watch for

* **Check titles** after searching. Search results are real listings and relevance varies.
* **Show totals** before asking for payment. Tax depends on the address.
* **Use the latest `review_hash`** from the most recent checkout response. A stale hash returns `review_changed`.
* **Never retry after `commit_unknown`.** Call `get_order` and wait. See [Handling checkout errors](https://agentmall.mintlify.site/examples/checkout-errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.