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

> Connect your agent and place a Walmart order in five minutes.

![Five steps: get key, connect, search, cart, checkout](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/quickstart.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=3ed29514b589284312e371cbb118cccb)

Connect your agent and place a Walmart order in five minutes.

You need an organization API key. Mint one in the [console](https://console.getagentmall.com/keys) or use the key from your welcome email.

## 1. Connect

The MCP server is streamable HTTP at `https://mcp.getagentmall.com`. Pass your key as a `Bearer` token.

```bash Claude Code theme={null}
claude mcp add --transport http agentmall https://mcp.getagentmall.com \
  --header "Authorization: Bearer YOUR_KEY"
```

```json Cursor (~/.cursor/mcp.json) theme={null}
{
  "mcpServers": {
    "agentmall": {
      "url": "https://mcp.getagentmall.com",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}
```

```text Other MCP clients theme={null}
Server URL: https://mcp.getagentmall.com
Header:     Authorization: Bearer YOUR_KEY
```

The REST API is at `https://api.getagentmall.com` with the same `Bearer` header.

## 2. Create a cart

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

`create_cart` returns an empty cart. The `id` in the response (a `ses_` string) is your cart ID for every later call.

This guide uses Walmart. To shop another store, call `list_merchants` and pass that store's `merchant_id` (for example `mrc_target` or `mrc_ocado`) here and in search. Every step below is the same.

`account: "platform"` uses a shared signed-in AgentMall account at the merchant and clears its cart. Omit `account` for a fresh shopper browser, then call `sign_in` before checkout.

## 3. Search

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

`search_catalog` returns up to 10 products with `id`, `title`, `price` (integer minor units, cents for USD), `url`, and `availability`.

Check titles before using a result. If `relevance` is `"low"`, the query was ambiguous — retry with a more specific term. For a single product, call `get_product` with the `url` and your `session_id` to get details, reviews, and variant options.

## 4. Add items to cart

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

`update_cart` replaces the entire cart. List every item you want, each with a quantity from 1 to 12. The URL must be the specific variant (size, colour) if the product has options.

The response returns `line_items` and `totals` with the live cart contents.

## 5. Start checkout

```json theme={null}
{
  "cart_id": "ses_…"
}
```

`create_checkout` opens checkout on the merchant site and returns:

* `line_items` — what's in the order
* `totals` — subtotal, tax, fees, total (all integer minor units)
* `fulfillment.methods` — shipping, delivery, or pickup options
* `review_hash` — a fingerprint of this exact review state
* `status` — `"incomplete"` until address and payment are set

Nothing is placed yet.

## 6. Set address and payment

```json theme={null}
{
  "id": "ses_…",
  "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"
    }
  },
  "payment": {
    "instruments": [
      {
        "id": "card_1",
        "handler_id": "dev.agentmall.card",
        "type": "card",
        "selected": true,
        "credential": { "type": "ciphertext", "value": "ev:…" }
      }
    ]
  }
}
```

`update_checkout` writes the address and card. The card `credential.value` is an Evervault `ev:` ciphertext collected through the console vault page. AgentMall never sees the raw card number.

Call with only `fulfillment.address` first to see estimated tax and total before asking for a card. The response includes an updated `review_hash` and `totals`.

## 7. Place the order

```json theme={null}
{
  "id": "ses_…",
  "review_hash": "abc123…",
  "total_minor": 12640
}
```

`complete_checkout` places the order when the `review_hash` and `total_minor` match the live review. One approval, one merchant commit. The response includes `order.id` and `status: "completed"`.

**If the review changed** since you last read it, you get `review_changed` with the `reason` and `changes`. Nothing was placed. Read the checkout again, show the new review to the user, and confirm again.

**If `commit_unknown`** is returned, the order may have been placed. Do not retry. Call `get_order` with the order ID and wait for confirmation.

**Test keys** (`am_test_`) run the full flow — the review is read and checked — but nothing is submitted to the merchant. The order is stored with `test: true` and no fee is charged.

## 8. Check the order

```json theme={null}
{
  "id": "ord_…"
}
```

`get_order` returns `status`, `totals`, `merchant_status`, and `permalink_url`. No session needed.

## Next steps

* [Sessions and Carts](https://agentmall.mintlify.site/concepts/sessions.md) — session lifecycle and cart state
* [Checkout](https://agentmall.mintlify.site/concepts/checkout.md) — the five-step checkout flow in detail
* [Review and Safety](https://agentmall.mintlify.site/concepts/review-safety.md) — why review\_hash exists and how to handle changes
* [Error Codes](https://agentmall.mintlify.site/reference/errors.md) — every error code with recovery guidance
* [MCP Tools](https://agentmall.mintlify.site/mcp/tools.md) — full tool reference with inputs and error tables


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