Skip to main content

​
Stateset iCommerce Architecture

​
AI‑powered order flow from conversation to fulfillment

Stateset iCommerce is a vertically integrated commerce operating system. It lets AI agents run a complete purchase and support lifecycle inside a natural conversation while the platform executes every operational step in the background. At a high level, the system combines:
  • Conversational AI agents for shopping, support, and operations
  • Agentic Commerce Protocol (ACP) for secure AI‑initiated checkout and delegated payment
  • Model Context Protocol (MCP) for tool execution and in‑chat widgets
  • StateSet API as the unified backend for orders, inventory, payments, fulfillment, returns, and finance
  • StateSet Sync Server for multi‑tenant routing and integrations (Shopify, ERPs, 3PLs, marketplaces)
This document is the technical + business explainer for how those layers work together. For implementation details, see the linked guides at the end.

​
System architecture

​
Conversation & Agent Layer

Three specialized agents collaborate in one session:
  • Commerce Agent: product discovery, recommendations, cart building, ACP checkout.
  • Customer Service Agent: tracking, returns, warranties, order modifications, escalation.
  • Operations Agent: inventory checks, fulfillment routing, sync jobs, exception handling.
Agents invoke platform tools through MCP, which also renders rich widgets (product carousels, order records, tracking views) inline in the conversation.

​
Transaction Layer (ACP)

ACP is the secure “handshake” that allows an AI agent to initiate and complete purchases:
  1. Create checkout with line items and currency.
  2. Update checkout with buyer identity and shipping/billing details.
  3. Delegate payment to get a scoped, time‑boxed, single‑use token.
  4. User confirms in‑chat.
  5. Complete checkout to capture payment and create the order.
ACP guarantees explicit consent, auditability, and safe retries via idempotency.

​
Core iCommerce Engine

Once ACP completes, the iCommerce Engine executes the lifecycle:
  • Orders: creation, state machine, line items, split shipments.
  • Inventory: multi‑location availability, reservations, backorder logic.
  • Payments: capture, refunds, chargebacks (gateway‑agnostic).
  • Fulfillment: routing to the best warehouse/3PL, shipment records, tracking.
  • Returns & warranties: eligibility, labels, restock, replacement orders.
  • Finance: double‑entry postings for revenue, COGS, refunds.
Everything is event‑driven: order/payment/fulfillment events flow through an outbox and fan out to integrations and UI updates.

​
External Integrations

The Sync Server provides:
  • Multi‑tenant configuration per merchant/brand.
  • Real‑time webhooks + batch sync jobs.
  • Field mapping and normalization.
  • Circuit breakers, retries, and per‑tenant rate limits.
This is what lets iCommerce coexist with (or replace) existing stacks.

​
End‑to‑end flow (conversation → fulfillment)

  1. Customer asks for a product in natural language.
  2. Commerce Agent searches catalog and presents options in a widget.
  3. Customer selects an item; agent creates an ACP checkout session.
  4. Agent collects shipping/buyer details conversationally and updates checkout.
  5. Agent delegates payment; customer sees summary and explicitly confirms.
  6. ACP completes checkout: payment captured and order created.
  7. Sync Server routes order to the optimal fulfillment center.
  8. Inventory is reserved at the chosen location.
  9. Fulfillment partner ships; tracking updates stream back via webhooks.
  10. Customer Service Agent handles post‑purchase (tracking, returns, warranty) in the same conversation.
For a concrete multi‑agent Shopify → NetSuite → 3PL pipeline, see the workflows guide below.

​
Security and trust model

Agentic commerce must be safe by default. iCommerce enforces:
  • Scoped delegated payments: tokens are bound to a checkout session, amount, and expiry.
  • Explicit consent: the buyer must confirm before payment capture.
  • Time limits + single use: tokens expire quickly and cannot be replayed.
  • Idempotency keys: retries never double‑charge or duplicate orders.
  • Audit trail: every agent action and ACP call is logged with request IDs.
  • PCI isolation: sensitive payment data stays with the gateway.

​
Adoption paths

​
Merchants on an existing stack

  1. Enable ACP endpoints for checkout and delegated payment.
  2. Register MCP tools for product search, add‑to‑cart, order/return/tracking actions.
  3. Connect systems to the Sync Server (Shopify/marketplaces, ERP, 3PL).
  4. Start with one workflow (orders + tracking), then expand to returns, warranties, finance, and proactive ops.

​
Marketplaces or multi‑brand operators

  1. Onboard each tenant with isolated credentials, mappings, and rate limits.
  2. Share the agent layer across tenants while keeping data and outcomes isolated.
  3. Route orders per tenant policy (warehouse rules, SLA, costs).