A production-ready universal engine for Agentic Commerce. This tool enables autonomous agents to interact with any compatible headless e-commerce backend through a standardized protocol. It provides out-of-the-box support for discovery, cart operations, and secure user management.
The Standard Agentic Commerce Engine is a standard client and protocol guide for connecting agents to compatible e-commerce backends. It gives agents a consistent way to search products, manage carts, access account data, create orders, and hand payment back to the user.
GitHub Repository: https://github.com/NowLoadY/agent-commerce-engine
The agent-commerce-engine includes a server specification in SERVER_SPEC.md for sites that want to expose a compatible commerce API. By implementing the documented endpoints, an existing storefront can support agent-driven product discovery, cart actions, account flows, and order creation without requiring a custom tool for each brand.
For a production-grade implementation example using this engine, see the Lafeitu Gourmet Skill. It demonstrates the engine specialized for a real-world artisanal food brand.
To ensure transparency and protect user data, the Standard Agentic Commerce Engine follows these security protocols:
~/.openclaw/credentials/agent-commerce-engine/0600 (user-only) permissions.logout command.x-api-token headers for authentication. Raw passwords are only transmitted once during the login or register phase to exchange for a token.localhost and 127.0.0.1 remain available for local development.Visitor ID (UUID v4) is generated and stored locally. This ID contains no personal information.To provide the most accurate and efficient experience, follow this priority sequence:
commerce.py script first. It provides structured, high-precision data. Target a store via --store <url> argument.x-user-account, x-visitor-id) to maintain session integrity without cookies.search results as the source of truth for the backend.Follow these logical flows to ensure a high-quality user experience:
Goal: Ensure the item exists and find the correct specifications before taking action.
search or list before adding to cart.slug and valid variant specs. Use --page and --limit arguments to safely navigate large catalogs without overwhelming the context limit.totalPages > page in the results, consider fetching the next page or refining the search.Goal: Manage user privacy and session data.
401 Unauthorized if credentials aren't saved.python3 scripts/commerce.py get-profilepython3 scripts/commerce.py update-profile --name "Name" --address "..." --phone "..." --email "..."Goal: Handle new users.
send-code and register commands when the backend supports them. If a backend only returns a registration URL, hand the user to that flow.Goal: Precise modification of the user's shopping session.
python3 scripts/commerce.py add-cart <slug> --variant <V> --quantity <Q>python3 scripts/commerce.py update-cart <slug> --variant <V> --quantity <Q>python3 scripts/commerce.py remove-cart <slug> --variant <V>python3 scripts/commerce.py clear-cartpython3 scripts/commerce.py create-order --name <NAME> --phone <PHONE> --province <PROVINCE> --city <CITY> --address <ADDRESS>create-order, the API typically returns a URL. The Agent MUST hand this URL to the human user to finalize payment.Goal: Access brand identity and support data.
brand-info interface to retrieve narrative content.python3 scripts/commerce.py brand-story: Get the narrative/mission.python3 scripts/commerce.py company-info: Get formal details.python3 scripts/commerce.py contact-info: Get customer support channels.search / list: Product discovery and inventory scan. Use --page <N> and --limit <N> to safely paginate through large catalogs.get: Deep dive into product specifications, variants, and pricing.promotions: Current business rules, shipping thresholds, and active offers.cart: Complete session summary including VIP discounts and tax/shipping estimates.add-cart / update-cart / remove-cart / clear-cart: Atomic cart control.create-order: Finalize cart into a pending order and secure payment URL for user handoff.get-profile / update-profile: Personalization and fulfillment data.brand-story / company-info / contact-info: Brand context and support.orders: Real-time tracking and purchase history.# Target a store directly via --store (preferred)
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 list --page 1 --limit 20
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 search "item"
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 add-cart <slug> --variant <variant_id>
# Or use environment variable (deprecated, will be removed in a future version)
export COMMERCE_URL="https://api.yourbrand.com/v1"
python3 scripts/commerce.py list
Credentials are automatically stored per-domain under ~/.openclaw/credentials/agent-commerce-engine/<domain>/.
AUTH_REQUIRED: Token missing or expired. Run login to obtain a new token.AUTH_INVALID: Wrong credentials. Verify account and password.PRODUCT_NOT_FOUND: Resource not found. Verify slug via search.VARIANT_UNAVAILABLE: The requested variant is invalid or out of stock. Check the instruction field for available alternatives.CART_EMPTY: Attempted checkout with no items. Add items first.--store URL is correct and the endpoint is reachable.