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.

1. Connect

See Connect your agent. Confirm the host lists the agentmall tools.

2. Create a session

{ "shopper_id": "shp_demo", "merchant_id": "mrc_walmart" }

Keep the returned session_id for every later call. Sessions start as a signed-out guest browser.

3. Search

Catalog (default):

{ "merchant_id": "mrc_walmart", "query": "AA batteries" }

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

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

4. Add to cart

{
  "session_id": "ses_…",
  "url": "<url from search>",
  "quantity": 1
}

product_id is optional correlation only. Confirm with read_cart.

5. Place order — review

Guest checkout: pass an address and a card (or vault refs). Prefer vault_ref so PANs never sit in tool logs.

{
  "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: "awaiting_confirmation" and a review with lines, totals, review_hash, and total / amount in minor units. Nothing is placed yet.

6. Place order — commit

Show the review to your user. Call again with the same address/payment inputs plus:

{
  "session_id": "ses_…",
  "address": { "…" },
  "card": { "…" },
  "confirmation": "yes, place it for $16.97",
  "review_hash": "<from review>",
  "total_minor": 1697
}

If the cart or total changed, you get review_changed / total_mismatch — get a fresh review and confirm again. If you get commit_unknown, call get_order and do not retry.

7. Track

{ "session_id": "ses_…", "order_id": "ord_…" }

Or open Sessions and Orders in the console with your key.

Next

• Auth and keys — caps and 401s
• Errors — codes your agent should handle
• Order flow — states after placement
• MCP tools — full input tables