> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iCommerce Architecture

> How Stateset powers agentic commerce from conversation to fulfillment

# 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

```mermaid theme={null}
graph TD
    subgraph "Conversation & Agent Layer"
        U[Customer in ChatGPT / Voice / SMS]
        A[Commerce Agent]
        S[Customer Service Agent]
        O[Operations Agent]
        M[MCP Server & Widgets]
    end

    subgraph "Transaction Layer"
        ACP[Agentic Commerce Protocol]
        PAY[Delegated Payment Providers<br/>Stripe, PayPal, etc.]
    end

    subgraph "Core iCommerce Engine"
        API[StateSet API<br/>Orders · Inventory · Payments · Returns · Finance]
        SYNC[StateSet Sync Server<br/>Multi‑tenant routing & jobs]
        DB[(PostgreSQL + Redis)]
        EVT[Event Bus / Outbox]
    end

    subgraph "External Integrations"
        MP[Marketplaces<br/>Shopify · Amazon · TikTok · Walmart]
        ERP[ERP / Accounting<br/>NetSuite · SAP · QuickBooks]
        WMS[3PL / WMS / Carriers<br/>DCL · Cart.com · UPS]
    end

    U --> M
    M --> A
    M --> S
    M --> O

    A --> ACP
    ACP --> PAY
    ACP --> API
    ACP --> SYNC

    API <--> DB
    API --> EVT
    EVT --> SYNC

    SYNC <--> MP
    SYNC <--> ERP
    SYNC <--> WMS
```

### 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).

***