Key Concepts

This page explains the fundamental concepts you’ll encounter when working with the Agentic Commerce Protocol. Understanding these terms will help you navigate the documentation and implement ACP effectively.

Core Concepts

AI Agent

An AI agent is a software system powered by artificial intelligence that can take actions on behalf of a user. In the context of ACP:

• The agent understands user requests in natural language
• It searches for products across multiple merchants
• It facilitates the checkout process
• It never handles actual payment credentials

Examples: ChatGPT, Claude, future AI assistants

Agentic Commerce

Agentic commerce refers to commercial transactions where AI agents act as intermediaries between buyers and sellers. Key characteristics:

• Autonomous discovery: AI finds products based on intent, not keywords
• Conversational interface: Users describe what they want naturally
• Cross-platform: Single conversation spans multiple merchants
• User-controlled: Humans approve all purchases

Checkout Session

A checkout session is a temporary container that holds the state of a purchase in progress. It includes:

• Cart items (products and quantities)
• Buyer information (shipping address, email)
• Calculated totals (subtotal, shipping, tax, total)
• Session state (ready/not ready for payment)
• Expiration time (typically 30 minutes)

{
  "checkout_session_id": "cs_abc123",
  "state": "ready_for_payment",
  "cart": { /* items */ },
  "totals": { /* calculated amounts */ },
  "expires_at": "2024-12-15T12:00:00Z"
}

Session States

A checkout session moves through defined states:

┌──────────────────────┐
│ not_ready_for_payment │ ← Missing required info
└──────────┬───────────┘
           │ Add shipping address
           ▼
┌──────────────────────┐
│  ready_for_payment   │ ← Can complete checkout
└──────────┬───────────┘
           │ Submit payment
           ▼
┌──────────────────────┐
│      completed       │ ← Order created
└──────────────────────┘

Payment Concepts

Shared Payment Token (SPT)

A Shared Payment Token is a secure, limited-use credential that allows a merchant to charge a specific amount. Key properties:

Delegated Payment

Delegated payment is the model where payment authorization is “delegated” from the user to a token system:

1. User has card stored with payment provider (Stripe)
2. User authorizes a payment for specific merchant/amount
3. Token is generated representing this authorization
4. Token is passed through AI agent to merchant
5. Merchant redeems token with payment provider

The AI agent is just a messenger—it can’t create tokens or modify amounts.

Merchant of Record

The merchant of record is the business legally responsible for the transaction. In ACP:

• The merchant (not OpenAI, not the AI agent) is the merchant of record
• Merchants handle refunds, chargebacks, and disputes
• Merchants are responsible for tax collection
• Merchants maintain the customer relationship

This is different from marketplace models where the platform is often the merchant of record.

Product Concepts

Product Feed

A product feed is a structured data file that describes a merchant’s available products. It enables AI agents to discover and search products.

{
  "products": [
    {
      "id": "sku_12345",
      "title": "Wireless Headphones",
      "description": "Premium over-ear headphones...",
      "price": 199.99,
      "currency": "USD",
      "availability": "in_stock",
      "category": "Electronics > Audio",
      "images": ["https://..."]
    }
  ]
}

Product Variant

A variant is a specific version of a product that differs by attributes like size, color, or material:

{
  "id": "prod_tshirt",
  "title": "Classic T-Shirt",
  "variants": [
    {"id": "var_small_blue", "size": "S", "color": "Blue", "price": 29.99},
    {"id": "var_medium_blue", "size": "M", "color": "Blue", "price": 29.99},
    {"id": "var_large_red", "size": "L", "color": "Red", "price": 29.99}
  ]
}

Availability States

Products have availability states that AI agents check before adding to cart:

API Concepts

Idempotency

Idempotency means that making the same request multiple times produces the same result. ACP uses idempotency keys to prevent duplicate orders:

POST /checkout_sessions/cs_123/complete
Idempotency-Key: order_abc123_attempt_1

If this request is accidentally sent twice, only one order is created.

Request Signing

Request signing is a security measure where requests include a cryptographic signature proving they came from an authorized source:

Signature: sha256=abc123...
Timestamp: 2024-12-15T10:30:00Z

The signature is calculated from:

• Request timestamp
• Request body
• Shared secret key

This prevents request tampering and replay attacks.

Webhooks

Webhooks are HTTP callbacks that notify your system when events occur:

Merchant Server                    Your System
      │                                │
      │  POST /webhooks/acp            │
      │  {                             │
      │    "event": "order.created",   │
      │    "order_id": "ord_123"       │
      │  }                             │
      │ ──────────────────────────────►│
      │                                │
      │        200 OK                  │
      │ ◄──────────────────────────────│

Common webhook events:

• checkout.session.created
• checkout.session.completed
• order.created
• order.shipped
• order.delivered

Architecture Concepts

Three-Party Model

ACP uses a three-party model where each participant has distinct responsibilities:

Trust Boundaries

Trust boundaries define what each party can and cannot access:

┌─────────────────────────────────────────────────────────┐
│                     User's Domain                        │
│  • Payment credentials (stored with Stripe)              │
│  • Full purchase history                                 │
│  • Personal preferences                                  │
└─────────────────────────────────────────────────────────┘
                           │
           Token (limited) │ Address (necessary)
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   AI Agent's Domain                      │
│  • Conversation context                                  │
│  • Product search results                                │
│  • Checkout session state                                │
│  • Payment tokens (opaque, limited)                      │
└─────────────────────────────────────────────────────────┘
                           │
               Token + Address
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Merchant's Domain                      │
│  • Order details                                         │
│  • Shipping address                                      │
│  • Payment confirmation                                  │
│  • Fulfillment data                                      │
└─────────────────────────────────────────────────────────┘

Stateless vs. Stateful

ACP components vary in how they manage state:

Integration Concepts

Integration Levels

Merchants can integrate at different levels:

Platform Integration

Use a pre-built integration from your e-commerce platform:

• Shopify app
• WooCommerce plugin
• BigCommerce connector

Effort: Hours | Control: Limited

Stripe Agent Toolkit

Use Stripe’s SDK with pre-built ACP support:

import { AgentToolkit } from '@stripe/agent-toolkit';
const toolkit = new AgentToolkit({ stripe });

Effort: Days | Control: Moderate

Full API Implementation

Build your own implementation of all three specifications:

• Product feed endpoint
• Checkout API endpoints
• Payment handling

Effort: Weeks | Control: Complete

API Versioning

ACP uses URL path versioning:

https://merchant.com/acp/v1/checkout_sessions
                        ↑
                   Version number

Version changes:

• Major version (v1 → v2): Breaking changes
• Minor updates: Backwards-compatible additions

Common Patterns

Optimistic UI

AI agents often use optimistic UI patterns—showing expected results before confirmation:

AI: "I'm adding the garden tools to your cart..."
    [Shows cart immediately]

    "Cart updated! Ready to checkout when you are."
    [Confirms after API responds]

Progressive Disclosure

ACP supports progressive disclosure of information:

1. Start with minimal info (just cart items)
2. Add shipping when needed
3. Add payment when ready
4. Complete only with full confirmation

This reduces friction and lets users exit at any point.

Error Recovery

ACP is designed for graceful error recovery:

• Sessions can be resumed if interrupted
• Idempotency prevents duplicate orders
• Clear error codes enable intelligent retry logic
• Expired sessions can be recreated with same cart

Glossary Quick Reference

Next Steps