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

# Overview

> Agentic commerce execution for AI agents

**AgentMall lets AI agents buy things for people, safely.** Your agent searches, builds a basket and asks its human to approve. AgentMall runs the purchase at the merchant and records every step.

It is built for developers integrating commerce into agent workflows: personal shopping assistants, procurement bots, reorder automations, and any system where an AI agent acts on a human's behalf to find and purchase goods.

> [card] Discover
>
> Search catalogs, view products and compare offers across merchants.

> [card] Approve
>
> The human approves the exact basket, quote and route plan before anything is bought.

> [card] Execute
>
> The order is placed with the approved mandate. Your agent never handles raw credentials or card
> numbers.

> [card] Audit
>
> Every step is recorded in an append-only evidence trail.

## What is AgentMall

AgentMall is an agentic commerce execution platform. It gives AI agents a structured way to search catalogs, build baskets, obtain human approval, and execute purchases, with every step recorded and auditable.

The platform sits between your agent and the merchants it buys from. Your agent never handles raw credentials, never sees card numbers, and never submits an order without explicit approval from the human who authorized it.

## How you connect

Your agent connects to AgentMall through its MCP server.

Test mode needs no account or key, and returns real Walmart search results. Carts, checkout and orders need a test key.

> [card] [Connect your agent](https://agentmall.mintlify.site/connect-your-agent.md)
>
> Add the test-mode server to Claude Code, Cursor or another MCP client.

> [card] [MCP tools reference](https://agentmall.mintlify.site/mcp/tools.md)
>
> Every tool the server exposes, with its inputs.

## The core loop

Every agent interaction follows the same lifecycle, whether the session ends in a purchase or the agent abandons after browsing:

**1. Shopper**

Create the shopper with a delivery address and enroll a payment method on the hosted vault page.

**2. Session**

Create a session explicitly, then pass its ID on every shopping call.

**3. Discovery**

The agent searches the catalog, views products, and compares offers across merchants.

**4. Basket**

The agent builds a single-merchant cart with specific items and quantities.

**5. Quote and approval**

A checkout session returns the quote and route plan. The human approves those terms and receives
a mandate.

**6. Execution**

Complete checkout with that mandate and an idempotency key. Only then does the platform create
an order.

**7. Confirmation**

The order enters the fulfillment lifecycle and the agent can track its state.

**8. Post-purchase**

Returns, refunds, and cancellations flow through the same structured path.

`browsing` and `carted` describe an open session's current stage. A session becomes `abandoned` only when it ends without an order.

## How the tools are organized

The MCP tools are organized around the objects an agent interacts with during a purchase:

| Objects | What they do |
| - | - |
| **Shoppers and vault** | Store delivery details and opaque payment references before the agent begins shopping. |
| **Sessions** | Give every catalog, cart, checkout, and attribution call one shared interaction reference. |
| **Catalog** | Search products across merchants and receive structured offers. |
| **Carts** | Build and modify baskets before checkout. |
| **Checkout and approval** | Price a cart, disclose the route plan, and obtain a one-basket mandate before execution. |
| **Orders and post-purchase** | Track fulfillment, returns, refunds, and the append-only evidence trail. |

> [!NOTE]
>
> These docs are deployed from the repository via Git sync. Content edits merged to `main` appear
> here automatically.


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