Agentic Commerce Flow

Overview

What ChatBasket does: It hosts your merchant ACP and UCP endpoints and returns an explicit decision (allow, review, clarify, deny) for every agent-submitted order intent.

You keep ownership of checkout, OMS, inventory, and fulfillment. ChatBasket provides the policy, approvals, audit trail, and safe forwarding needed to participate in agentic checkout via ACP, Google's Universal Commerce Protocol (UCP), and other emerging standards. Policy is defined in the Merchant Policy Schema (v1).

Order Intent Flow

flowchart TD
  A["Agent submits order intent
SKU-level via ACP/UCP"]
  A2["Agent fixes required fields"]

  B["ChatBasket receives intent"]
  C["ChatBasket evaluates policy"]

  A --> B --> C
  A2 --> A

  C -->|ALLOW| D["Approved intent"]
  C -->|REVIEW| E["Pending human review"]
  C -->|DENY| G["Rejected (explicit)"]
  C -->|CLARIFY| F["Needs clarification
required_fields"]

  D --> H["Forward intent to merchant OMS"]
  H -->|OMS 2xx| I["Order created
in merchant systems"]
  H -->|OMS error| J["Explicit failure
returned to agent"]

  E --> K{"Human decision"}
  K -->|Approve| D
  K -->|Reject| G

  F --> A2

  I --> M["ACP decision returned (approved)"]
  G --> N["ACP decision returned (rejected)"]

  subgraph POST["Post-Order Updates"]
    direction LR
    S["Merchant sends status update"]
    T["ChatBasket relays to agent"]
  end

  I -.-> S
  S --> T

Roles & Responsibilities

This section clarifies the responsibility and trust boundaries between agent developers, ChatBasket, and merchants. ChatBasket is neutral infrastructure that hosts the merchant’s ACP endpoint.

What ChatBasket owns (the governance layer)

Merchant ACP & UCP endpoints — authenticated intent intake, rate limiting, and idempotency.
Policy engine — schema-backed rules that return deterministic decisions with reason codes and required fields.
Clarification management — structured requests for missing or ambiguous inputs and re-evaluation on resubmission.
Human approval workflows — review queues, reviewer actions, RBAC, and escalation paths.
Audit & replay — a complete log of every intent, decision, actor, and timestamp, plus tooling to replay intents against policy.
Safe forwarding — idempotent delivery of approved intents to merchant systems with explicit error handling.
Status relay — propagation of downstream order status updates back to agents via ACP-style notifications.

AI Agent

Selects SKUs from a known product catalog
Submits SKU-level purchase intent via ACP, UCP, or other protocols
Handles clarification, approval, or rejection responses

Universal Commerce Protocol (UCP)

Google's open standard for agentic commerce across AI surfaces
Uses .well-known/ucp manifest for capability discovery
Compatible with AP2, A2A, and MCP protocols
Powers checkout on Google Search AI Mode and Gemini
Merchant retains Merchant of Record status and customer data

Agentic Commerce Protocol (ACP)

Standardizes how intent, clarification, and confirmation are expressed
Provides stable transaction identifiers
Defines states such as approved, pending_review, needs_clarification, rejected

Merchant Systems

Create the actual order
Own pricing, inventory, fulfillment, and compliance
Only receive approved intent

Why this is safe for merchants

ChatBasket makes agentic checkout safe and operable for merchants by turning every agent request into an explicit, auditable decision before it reaches checkout.

Deterministic policy with explainable outcomes (allow, review, clarify, deny)
Human approvals for high-risk intents, without exposing checkout
Complete audit trail for compliance, disputes, and debugging
Approved-intent forwarding into your existing OMS/ERP, with explicit failure handling

This model lets you accept agent-driven demand via ACP, UCP, and emerging protocols without rebuilding checkout or trusting opaque agent behavior. It's policy-first governance, designed for protocol-native commerce.

Technical details

The sections below describe the ACP/UCP states, payloads, and decision flow for engineers integrating agents or merchant systems.

API Authentication

Each AI agent is registered in the ChatBasket Control Plane and assigned an API key. All requests must include this key in the header:

POST /api/v1/intent
X-API-Key: cb_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

The API key identifies both the agent and the merchant. You can generate and manage API keys from the Agents section in the Control Plane.

Purchase Intent (ACP Input)

Agents submit SKU-level intent. The agent and merchant are identified via the API key. Free-text item matching is handled upstream of ACP.

ChatBasket returns a stable transaction_id for each intent, which is used across approvals, clarifications, and status updates.

POST /api/v1/intent
X-API-Key: cb_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "externalIntentId": "intent-123",
  "items": [
    {
      "sku": "SKU-12345",
      "name": "Organic Bananas",
      "quantity": 2,
      "unitPrice": 4.99,
      "category": "produce"
    }
  ],
  "customer": {
    "id": "cust_456",
    "email": "customer@example.com"
  },
  "shippingAddress": {
    "zip": "94105"
  }
}

Policy Evaluation

ChatBasket evaluates intent against your rules, defined in the Merchant Policy Schema (v1). Decisions are deterministic and auditable.

ALLOW – auto-approve
REVIEW – human approval required
DENY – hard reject
CLARIFY – missing or ambiguous information

Decision to ACP status mapping: ALLOW → approved, REVIEW → pending_review, CLARIFY → needs_clarification, DENY → rejected.

ACP Decision Responses

Approved

{
  "transaction_id": "acp-txn-123",
  "status": "approved"
}

Pending Human Approval

{
  "transaction_id": "acp-txn-123",
  "status": "pending_review",
  "reason_codes": ["ORDER_VALUE_REVIEW"]
}

Needs Clarification

{
  "transaction_id": "acp-txn-123",
  "status": "needs_clarification",
  "required_fields": [
    {
      "field": "fulfillment.store_id",
      "reason": "STORE_REQUIRED_FOR_PICKUP"
    }
  ]
}

Rejected

{
  "transaction_id": "acp-txn-123",
  "status": "rejected",
  "reason_codes": ["CATEGORY_RESTRICTED"]
}

Human Approval

When review is required, ChatBasket routes the transaction to a reviewer. They can approve, reject, or request clarification. Every action is logged.

Forwarding to Merchant Systems

When an order intent is approved (auto-allow or after human review), ChatBasket sends a webhook notification to your OMS. Your merchant systems then create the actual order. Configure your webhook endpoint in Settings to receive approved intents.

POST https://your-oms.example.com/webhook
X-ChatBasket-Signature: sha256=...

{
  "event": "intent.approved",
  "intent": {
    "id": "...",
    "externalIntentId": "intent-123",
    "items": [...],
    "totals": { "total": 9.98 },
    "policyDecision": { "decision": "allow" }
  }
}

If your OMS returns an error while forwarding an approved intent, ChatBasket records the failure and returns a clear response to the agent so the integration is debuggable end-to-end.

Guarantee: Orders are created only after approval. Decisions are explicit and auditable.