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

# Quickstart

> From first search to a confirmed Walmart order.

You need a beta partner API key. This walkthrough uses MCP tool names; the same steps work on [REST](https://agentmall.mintlify.site/api/rest.md).

## 1. Connect

See [Connect your agent](https://agentmall.mintlify.site/connect-your-agent.md). Confirm the host lists the `agentmall` tools.

## 2. Create a session

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

Keep the returned `session_id` for every later call. Pass `account: "platform"` when the AgentMall Walmart context is configured (already signed in; cart cleared on create). Omit it for a signed-out guest browser.

## 3. Search

Catalog (default):

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

If results look empty or off-topic (common for groceries), retry with live merchant search:

```json theme={null}
{
  "merchant_id": "mrc_walmart",
  "query": "AA batteries",
  "source": "merchant",
  "session_id": "ses_…"
}
```

Each item includes `title`, `price`, `availability`, `product_id`, and a `url` for the cart. **Check titles before you use a result.** When the user wants more detail on one hit, call `get_product` with that `product_id` (same catalog fields today, not a full PDP).

## 4. Add to cart

```json theme={null}
{
  "session_id": "ses_…",
  "url": "<url from search>",
  "quantity": 1
}
```

`product_id` is optional correlation only. Confirm with `read_cart`.

## 5. Prepare checkout

Call `prepare_checkout`. Guest checkout: pass an address and a card (or vault refs). Prefer `vault_ref` so PANs never sit in tool logs. A platform session can omit both and keep the merchant defaults.

```json theme={null}
{
  "session_id": "ses_…",
  "address": {
    "name": "Alex Partner",
    "line1": "1 Market St",
    "city": "San Francisco",
    "region": "CA",
    "postal": "94105"
  },
  "card": {
    "number": "…",
    "expiration_month": 12,
    "expiration_year": 2030,
    "cvc": "…"
  },
  "delivery_preference": "shipping"
}
```

Response: `status: "prepared"` and a `review` with lines, money, `review_hash`, and `total.amountMinor`. **Nothing is placed yet.**

## 6. Checkout

Show the review to your user. Call `checkout` with only the hash and total:

```json theme={null}
{
  "session_id": "ses_…",
  "review_hash": "<from review>",
  "total_minor": 1697
}
```

If the cart or total changed, you get `review_changed` / `review_mismatch` / `total_mismatch` — call `prepare_checkout` again. If you get `commit_unknown`, call `get_order` and **do not retry**. On `placed`, the session ends.

## 7. Track

```json theme={null}
{ "session_id": "ses_…", "order_id": "ord_…" }
```

Or open [Sessions](https://console.getagentmall.com/sessions) and [Orders](https://console.getagentmall.com/orders) in the console with your key.

## Next

* [Auth and keys](https://agentmall.mintlify.site/auth-and-keys.md) — caps and 401s
* [Errors](https://agentmall.mintlify.site/errors.md) — codes your agent should handle
* [Order flow](https://agentmall.mintlify.site/concepts/order-flow.md) — states after placement
* [MCP tools](https://agentmall.mintlify.site/mcp/tools.md) — full input tables


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