Medusa

The API provides both REST (primary) and a storefront client SDK. The admin API covers products, collections, orders, customers, discounts, shipping, regions, and more. Resources follow standard CRUD patterns with consistent pagination, filtering, and response formats. The storefront API is a read-heavy subset for customer-facing operations. Webhooks notify on order events, payment captures, and fulfillment status changes. The API design is clean and well-structured for the e-commerce domain.

Error handling follows REST conventions with structured JSON error responses. The main operational complexity is order state management — orders move through a defined lifecycle (placed → paid → fulfilled → shipped → completed) and agents must handle state transitions correctly. The webhook system is reliable for event-driven workflows. Self-hosted deployments require infrastructure management (database, cache, file storage), which adds operational overhead compared to managed platforms.

Medusa is an open-source headless commerce engine that provides the backend for custom e-commerce experiences. For agents managing online stores — creating products, processing orders, managing inventory, handling customer data — Medusa provides a well-structured API. The modular architecture means agents can work with a focused set of APIs (products, orders, customers, payments) without navigating a monolithic platform. Being open-source means agents can inspect the full codebase when the API behavior is unclear.

Authentication uses API tokens for admin access and session-based auth for storefront. Admin tokens have full access — there are no per-resource permissions, which simplifies agent integration but limits multi-tenant isolation. For self-hosted deployments, network-level access control supplements token auth. The auth model is appropriate for single-tenant agent deployments but would need enhancement for platforms serving multiple merchants.

Documentation is comprehensive and well-maintained. The API reference covers all endpoints with request/response examples. Guides cover recipes for common workflows (create a product, process an order, set up payments). The docs also cover self-hosting, deployment, and plugin development. The learning curve is reasonable for agents familiar with e-commerce concepts. The open-source community provides additional resources.