How to Build an Agent-Ready Ecommerce API

An agent-ready ecommerce API exposes the commerce capabilities an AI agent needs (products, inventory, pricing, cart, checkout, orders, fulfillment, cancellation and returns) in a form agents can use without guessing: typed schemas, explicit status enums, actionable errors, delegated authorization per shopper, idempotent writes, rate limits per agent, cursor pagination and signed webhooks.

Build the capabilities once behind your own API and keep your business rules there. Then expose them to agents through REST, an MCP server and commerce protocol adapters (ACP, UCP) as the channels you sell through require.

Most ecommerce APIs were built for your own storefront and apps, which know your quirks. Agents do not. They read field names and descriptions literally, retry on timeouts, call from many platforms at once and act on behalf of shoppers who are not looking at your site. A missing idempotency key becomes a double order; a vague status becomes a wrong promise to a customer. The general case is covered in APIs for AI agents; this article is the ecommerce-specific design.

Use explicit types, enums and units everywhere: amounts in minor units with currency codes, timestamps in ISO 8601 with time zones, statuses from closed lists. Describe every field in plain language in your OpenAPI or tool schema, because agents read descriptions. Keep IDs stable across feed, cart, checkout and order, so an item an agent found can be bought and then tracked. Return state with every write so the agent never has to guess what happened.

Separate three identities. The agent platform proves who it is with client credentials or signed requests (HTTP Message Signatures, RFC 9421, are used by UCP). The shopper delegates specific permissions to that platform through OAuth-style identity linking, so the agent can see this shopper's orders and nothing else. Payment authorization is separate again and handled through payment credentials, not API scopes. Scope tokens narrowly (read orders, create checkout, create return), make them revocable, and log every call with platform, shopper and scope. See AI agent identity and authentication and AI commerce payments.

Idempotency: require an idempotency key on every write (cart changes, checkout completion, cancellation, return creation), store the result per key, and return the original result on replay; reject the same key with a different payload. Rate limits: apply per agent platform and per shopper, return 429 with Retry-After, and publish limits so platforms can plan. Pagination: use cursor-based pagination with stable ordering for search and order lists; offset pagination produces duplicates and gaps when data changes between pages.

Return a stable error type and code, a human-readable message, the field at fault, whether retrying can help and suggested alternatives: another variant in stock, the new price, the nearest available delivery date. Distinguish errors the agent can fix itself from those requiring the shopper (verification, policy acceptance) and return a URL where the shopper can complete them. See agent UX for the general pattern.

Agents should not poll your order system. Emit signed webhooks for order created, payment captured, shipped, delivered, cancelled, return created, refund issued. Include event IDs and timestamps so receivers can deduplicate and order events, retry with backoff, and provide a way to fetch current state for reconciliation. Our guide to ecommerce webhooks covers delivery guarantees.

For assistants that use MCP, wrap the same API in a small set of task-shaped tools (search_products, check_availability, create_checkout, get_order_status, start_return) with descriptions written for models. Do not expose raw CRUD over every table. Keep consequential tools (complete checkout, cancel, return) behind shopper confirmation in the client and authorization on your server. See AI agent tool design.

An agent-ready ecommerce API is a well-designed commerce API with stricter guarantees: explicit states, actionable errors, separated identities, idempotent writes, fair limits and reliable webhooks. Keep the rules in one place and adapt it to each protocol and assistant. For the checkout flow in detail, see agentic checkout; for the full picture, the agentic commerce stack.