Skip to main content
Five steps: get key, connect, search, cart, checkout Connect your agent and place a Walmart order in five minutes. You need an organization API key. Mint one in the console 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.
The REST API is at https://api.getagentmall.com with the same Bearer header.

2. Create a cart

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

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

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

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

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

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

Next steps