Introduction to Lorn AI

Welcome to Lorn AI—the gateway that connects AI agents to real-world commerce.

What is Lorn AI?

Lorn AI is an Agentic Commerce Protocol (ACP) compliant gateway that enables AI assistants like ChatGPT to:

Discover products using natural language queries
Build shopping carts with multiple items from multiple merchants
Complete purchases with full checkout flows
Receive order updates via real-time webhooks

Think of Lorn AI as the bridge between conversational AI and e-commerce—allowing users to shop through their preferred AI assistant while merchants maintain full control over their catalog, pricing, and fulfillment.

The Agentic Commerce Protocol (ACP)

The Agentic Commerce Protocol is a specification developed by OpenAI that defines how AI agents can interact with merchant systems to facilitate purchases. It consists of three main components:

┌─────────────────────────────────────────────────────────────────┐
│                    Agentic Commerce Protocol                     │
├─────────────────────┬─────────────────────┬─────────────────────┤
│   Product Feed      │   Checkout Spec     │  Delegated Payment  │
│                     │                     │                     │
│ • Product catalog   │ • Cart management   │ • Secure payments   │
│ • Pricing & stock   │ • Address handling  │ • PSP integration   │
│ • Semantic search   │ • Order completion  │ • Token-based auth  │
└─────────────────────┴─────────────────────┴─────────────────────┘

1. Product Feed Specification

Merchants share structured product data (title, description, price, inventory, images) that enables accurate product discovery and display in AI interfaces.

2. Agentic Checkout Specification

Defines the REST endpoints for creating and managing checkout sessions—from cart creation through order completion.

3. Delegated Payment Specification

Enables secure payment processing through the merchant’s existing Payment Service Provider (PSP), keeping financial data under merchant control.

Where Lorn AI Fits

Lorn AI serves as the middleware layer that implements these specifications:

┌──────────────┐     ┌──────────────┐     ┌──────────────────────┐
│              │     │              │     │                      │
│   AI Agent   │────▶│   Lorn AI    │────▶│  Merchant Systems    │
│  (ChatGPT)   │◀────│   Gateway    │◀────│  (Supabase, PSP)     │
│              │     │              │     │                      │
└──────────────┘     └──────────────┘     └──────────────────────┘
       │                    │                       │
       │                    │                       │
   User intent         ACP-compliant           Product data
   & decisions          endpoints              & fulfillment

For AI Agents:

Lorn AI provides a clean, consistent API following the ACP specification
Semantic search makes natural language queries work out of the box
Checkout sessions track cart state across the conversation

For Merchants:

Your product catalog lives in your systems (Supabase, Shopify, etc.)
You control pricing, inventory, and fulfillment
Payments process through your existing PSP

Key Features

Semantic Product Search

Unlike traditional keyword search, Lorn AI uses vector embeddings to understand the meaning behind queries:

User Query	Traditional Search	Semantic Search
”something warm for winter”	❌ No results	✅ Jackets, sweaters, coats
”gift for a runner”	❌ Literal match only	✅ Running shoes, fitness trackers
”comfortable work from home outfit”	❌ Too vague	✅ Loungewear, athleisure

Multi-Brand Catalogs

A single Lorn AI instance can serve products from multiple merchants:

# Search across all connected brands
products = search_products(q="organic coffee")
 
# Results may include products from multiple vendors
# - "Blue Bottle Coffee - Ethiopia Yirgacheffe"
# - "Stumptown Coffee - Hair Bender Blend"
# - "Intelligentsia - Black Cat Classic Espresso"

Checkout Sessions

Full shopping cart functionality with:

Line items with variant selection (size, color, etc.)
Shipping address handling
Tax calculation (demo: 8% rate)
Shipping costs (demo: $7.99 ground)
Order totals with complete breakdowns

Webhook Events

Real-time notifications for order lifecycle:

order.created — Order placed
order.updated — Status changed
order.fulfilled — Items shipped

Use Cases

1. AI Shopping Assistant

Build a conversational shopping experience where users can:

Ask for product recommendations
Compare options and prices
Add items to cart
Complete checkout—all in chat

2. Voice Commerce

Integrate with voice assistants to enable hands-free shopping:

“Add coffee filters to my cart”
“What’s the total for my order?”
“Complete my purchase”

3. Automated Purchasing

Create AI agents that can:

Monitor inventory levels
Reorder supplies automatically
Compare prices across vendors

4. Multi-Merchant Marketplaces

Aggregate products from multiple sellers into a unified shopping experience with consistent search and checkout.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                              AI Agent Layer                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   ChatGPT   │  │   Claude    │  │  Custom AI  │  │  Voice Bot  │    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │
└─────────┼────────────────┼────────────────┼────────────────┼───────────┘
          │                │                │                │
          ▼                ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Lorn AI Gateway (ACP)                            │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                        FastAPI Application                        │  │
│  ├─────────────────┬─────────────────┬─────────────────────────────┤  │
│  │  Product APIs   │  Checkout APIs  │      Webhook Emitter        │  │
│  │  /acp/products  │  /checkout_*    │      /webhooks/emit         │  │
│  └────────┬────────┴────────┬────────┴──────────────┬──────────────┘  │
└───────────┼─────────────────┼───────────────────────┼──────────────────┘
            │                 │                       │
            ▼                 ▼                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           Backend Services                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐ │
│  │    Supabase     │  │  In-Memory      │  │    Merchant Webhook     │ │
│  │   + pgvector    │  │    Sessions     │  │       Receivers         │ │
│  │                 │  │                 │  │                         │ │
│  │ • Products      │  │ • Cart state    │  │ • Order notifications   │ │
│  │ • Embeddings    │  │ • Customer info │  │ • Fulfillment updates   │ │
│  │ • Variants      │  │ • Pricing       │  │                         │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

Next Steps

Ready to get started? Here’s your path:

Quickstart Guide — Make your first API call in 5 minutes
Authentication — Set up API keys and security
API Reference — Explore all endpoints
Build a Shopping Agent — Complete tutorial

Requirements

To use Lorn AI, you’ll need:

Requirement	Details
API Key	Obtain from your Lorn AI dashboard
HTTPS	All production traffic must use TLS
JSON	All request/response bodies are JSON

For self-hosted deployments:

Requirement	Details
Supabase	With pgvector extension enabled
OpenAI API Key	For embedding generation
Python 3.9+	FastAPI runtime

Introduction Quickstart