# CommerceAI

> CommerceAI is the e-commerce marketplace for every AI agent. A governed catalog of 600M+ US products, plus four agent-ready capabilities: search, price comparison, product-vs-product, and detailed Q&A. One MCP tool, no SDK required.

Connect one remote MCP server and your agent can search the US product catalog, compare products it already returned, and answer product questions, with merchant links for checkout. The one MCP tool is `shopping_agent`, at `https://commerceai.ai/mcp/` (Streamable HTTP, `Authorization: Bearer <API key>`). For product data in code, the Search API (`POST https://commerceai.ai/api/v1/catalog/search`, REST, same API key) returns ranked US products with offers from Amazon, Walmart, and Macy's.

## Start here

1. Sign in to the console at https://commerceai.ai/ with Google and create an API key under **API Keys**. The key is shown only once.
2. Every account gets 1,000 free credits on sign-up, reset to 1,000 on the 1st of each month (US Eastern time). 1 credit = $0.001.
3. Connect your MCP client to `https://commerceai.ai/mcp/` with the header `Authorization: Bearer <API key>`, then call `shopping_agent` with a `query`.

- [Quickstart](https://commerceai.ai/docs/guide/quickstart): create an API key, a prompt for coding agents, and the first call
- [Connect an MCP client](https://commerceai.ai/docs/guide/mcp-clients): Claude Desktop, Cursor, and Claude Code configuration

## Docs

- [Overview](https://commerceai.ai/docs/): what the tool does, scope, and how a call works
- [Agent Capabilities](https://commerceai.ai/docs/reference/shopping-agent): `shopping_agent` request parameters, response fields, comparison tables, usage
- [Search API](https://commerceai.ai/docs/reference/search-api): product search request parameters, product offers, responses, and limits
- [Outcomes](https://commerceai.ai/docs/reference/outcomes): SUCCESS, NEEDS_CLARIFICATION, NO_RESULTS, UNSUPPORTED, and what each costs
- [Errors & Retries](https://commerceai.ai/docs/reference/errors): error format, error codes, and retry rules
- [Conversations](https://commerceai.ai/docs/guide/conversations): continuing a conversation and referring to products with `selected_item_ids`
- [Credits](https://commerceai.ai/docs/guide/credits): how calls are charged and how to get credits
- [Limits & Scope](https://commerceai.ai/docs/guide/rate-limits): rate limits, timeouts, lifetimes, and out-of-scope requests

## Scope

- Supported: the US market with English replies; product search, comparison of products already shown, product Q&A, and follow-ups in the same conversation; text input.
- Not supported: markets other than the US, carts, orders, checkout, coupons and vouchers, store account sign-in, image input. The shopper buys on the merchant's page.
- Requests for carts, orders, coupons, store accounts, or other markets get a short refusal and are not charged. Image input is rejected with an error.

## Price

- 1 credit = $0.001. The smallest charge is 1 credit.
- Search API: 5 credits ($0.005) per request.
- `shopping_agent`: 325 credits per 1M input tokens, 650 credits per 1M output tokens, and 6 credits per tool call (a product search the agent runs inside the call; about 5 per call on average).
- Refusals and failed calls are free. Purchased credits do not expire and are used after free credits.
- Credit packages: $10, $100, $1,500, and $3,000, bought in **Billing** in the console. Volume plans: support@commerceai.ai
- Full details: [Price](https://commerceai.ai/docs/pricing)

## Common misconceptions

- There is one MCP tool, `shopping_agent`. Search, comparison, and product Q&A are capabilities of that tool, chosen by the `query` text. There is no separate search or compare tool and no mode parameter.
- The Search API is REST only. It is not an MCP tool.
- The MCP server is stateless and returns no `Mcp-Session-Id`. Your client keeps `conversation_id` and `item_id` values and sends them back to continue a conversation.
- CommerceAI does not place orders or handle payment. Results link to the merchant's product page.
- Every request needs an API key. There is no keyless access.

## Optional

- [GitHub](https://github.com/CommerceAI-ai/CommerceAI): documentation, client configuration examples, code examples, and an agent skill
- [MCP server card](https://commerceai.ai/.well-known/mcp/server-card.json): machine-readable server metadata