Name: Agent Commerce Engine
Availability: InStock
Author: nowloady

Standard Agentic Commerce Engine

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

Quick Start: Backend Integration

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.

Reference Case: Lafeitu

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.

🔒 Security & Privacy

To ensure transparency and protect user data, the Standard Agentic Commerce Engine follows these security protocols:

1. Local Credential Persistence

Storage Location:

~/.openclaw/credentials/agent-commerce-engine/

Mechanism: Account and session Token information is stored locally in JSON format. The credential file is written with
```
0600
```
(user-only) permissions.
Security Upgrade: Since version 1.4.0, raw passwords are never stored after the initial login. The engine exchanges the password for a signed cryptographic token.
Scope: Credentials are stored on the local machine for reuse by the current user environment.
Lifecycle: Credentials can be purged at any time by running the
```
logout
```
command.

2. Secure Transmission

Token-based Auth: Uses
```
x-api-token
```
headers for authentication. Raw passwords are only transmitted once during the
```
login
```
or
```
register
```
phase to exchange for a token.
HTTPS Enforcement: The client rejects non-HTTPS remote endpoints.
```
localhost
```
and
```
127.0.0.1
```
remain available for local development.
Encrypted Transport: Production traffic is expected to run over HTTPS so tokens are not sent over plain HTTP.

3. Anonymous Tracking (Visitor ID)

To support shopping carts for unauthenticated users, a unique, non-identifiable
```
Visitor ID
```
(UUID v4) is generated and stored locally. This ID contains no personal information.

🛠 Tool Priority & Fallback Strategy

To provide the most accurate and efficient experience, follow this priority sequence:

API First (Primary): Always attempt to use the
```
commerce.py
```
script first. It provides structured, high-precision data. Target a store via
```
--store <url>
```
argument.
Stateless Headers: Rely on the engine's built-in header management (
```
x-user-account
```
,
```
x-visitor-id
```
) to maintain session integrity without cookies.
Self-Correction: If the API returns a 404 for a specific slug discovered via browser, prioritize the API's
```
search
```
results as the source of truth for the backend.

🧠 Agent Operational Logic

Follow these logical flows to ensure a high-quality user experience:

1. Product Discovery & Validation

Goal: Ensure the item exists and find the correct specifications before taking action.

Action: Always run
```
search
```
or
```
list
```
before adding to cart.
Logic: Use the API to discover the correct
```
slug
```
and valid
```
variant
```
specs. Use
```
--page
```
and
```
--limit
```
arguments to safely navigate large catalogs without overwhelming the context limit.
Refinement: If multiple results are found, ask the user to specify based on the returned attributes. If
```
totalPages > page
```
in the results, consider fetching the next page or refining the search.

2. Authentication & Profile Flow

Goal: Manage user privacy and session data.

Logic: The API is stateless. Actions requiring identity will return
```
401 Unauthorized
```
if credentials aren't saved.

Commands:

View profile:
```
python3 scripts/commerce.py get-profile
```

Update details:

python3 scripts/commerce.py update-profile --name "Name" --address "..." --phone "..." --email "..."

Required Data: Respect the schema of the specific brand's backend.

3. Registration Flow

Goal: Handle new users.

Trigger: When the user needs a new account or the backend returns "User Not Found".
Instruction: Prefer the built-in
```
send-code
```
and
```
register
```
commands when the backend supports them. If a backend only returns a registration URL, hand the user to that flow.

4. Shopping Cart Management

Goal: Precise modification of the user's shopping session.

Logic: The engine supports incrementing quantities or setting absolute values.

Commands:

Add:

python3 scripts/commerce.py add-cart <slug> --variant <V> --quantity <Q>

Update:

python3 scripts/commerce.py update-cart <slug> --variant <V> --quantity <Q>

Remove:

python3 scripts/commerce.py remove-cart <slug> --variant <V>

Clear:
```
python3 scripts/commerce.py clear-cart
```

Checkout / Create Order (Handoff):

python3 scripts/commerce.py create-order --name <NAME> --phone <PHONE> --province <PROVINCE> --city <CITY> --address <ADDRESS>

Validation: Variant values must be strictly chosen from the product's available options list.
Payment Flow (Crucial): Agents currently cannot directly execute consumer payments (card/mobile wallets) due to a lack of financial authorization. Once an order is generated via
```
create-order
```
, the API typically returns a URL. The Agent MUST hand this URL to the human user to finalize payment.

5. Brand Information & Storytelling

Goal: Access brand identity and support data.

Logic: Use the
```
brand-info
```
interface to retrieve narrative content.

Tooling:

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

🚀 Capabilities Summary

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.

💻 CLI Configuration & Examples

# 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>/

🤖 Troubleshooting & Debugging

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.
Connection Error: Verify the
```
--store
```
URL is correct and the endpoint is reachable.

Agent Commerce Engine

AI Skill Market Insights

Quick Start

Manual Installation

TEAR & SHARE

Tags

Fire Your SEO Agency

Be Part of the 0+ Developer Community

Standard Agentic Commerce Engine

Quick Start: Backend Integration

Reference Case: Lafeitu

🔒 Security & Privacy

1. Local Credential Persistence

2. Secure Transmission

3. Anonymous Tracking (Visitor ID)

🛠 Tool Priority & Fallback Strategy

🧠 Agent Operational Logic

1. Product Discovery & Validation

2. Authentication & Profile Flow

3. Registration Flow

4. Shopping Cart Management

5. Brand Information & Storytelling

🚀 Capabilities Summary

💻 CLI Configuration & Examples

Or use environment variable (deprecated, will be removed in a future version)

🤖 Troubleshooting & Debugging

Marketing OS

Reddit Automation

Create PRD (pm-skills)

Financial Analyst

Channels

Learn

Compare

Company

Agents