Multi-Brand Catalogs

One of Lorn AI’s most powerful features is the ability to aggregate products from multiple merchants into a unified shopping experience. This enables AI agents to help users find the best products across brands without switching between different stores.

Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                           AI Shopping Agent                              │
│                                                                         │
│         "Find me the best wireless headphones under $200"               │
│                                                                         │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            Lorn AI Gateway                               │
│                                                                         │
│                    Unified Search & Checkout APIs                        │
│                                                                         │
└────┬───────────────────┬───────────────────┬───────────────────┬────────┘
     │                   │                   │                   │
     ▼                   ▼                   ▼                   ▼
┌─────────┐       ┌─────────┐       ┌─────────┐       ┌─────────┐
│  Sony   │       │  Bose   │       │  Apple  │       │ Jabra   │
│ Catalog │       │ Catalog │       │ Catalog │       │ Catalog │
└─────────┘       └─────────┘       └─────────┘       └─────────┘

How It Works

Unified Product Search

When you search across a multi-brand catalog, Lorn AI queries all connected merchants and returns a combined, ranked result set:

curl "https://{{YOUR_STORE_URL}}/acp/products?q=wireless+headphones&max_price=200" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Response:

{
  "items": [
    {
      "id": "sony_wh1000xm5",
      "title": "Sony WH-1000XM5 Wireless Headphones",
      "vendor": "Sony",
      "price": 199.99,
      "similarity_score": 0.94
    },
    {
      "id": "bose_qc45",
      "title": "Bose QuietComfort 45",
      "vendor": "Bose",
      "price": 179.99,
      "similarity_score": 0.91
    },
    {
      "id": "jabra_elite85h",
      "title": "Jabra Elite 85h",
      "vendor": "Jabra",
      "price": 149.99,
      "similarity_score": 0.88
    }
  ],
  "page": 1,
  "page_size": 10,
  "total": 3
}

Products from different vendors appear together, ranked by semantic relevance to the query.

Vendor Identification

Each product includes its source vendor:

Field	Description
`vendor`	Brand/manufacturer name
`id`	Unique product ID (scoped to vendor)

This allows agents to present options like:

“I found wireless headphones from Sony, Bose, and Jabra. The Sony WH-1000XM5 is highly rated at $199.99, while the Bose QuietComfort 45 is $179.99…”

Filtering by Brand

Single Brand Filter

Search within a specific brand:

curl "https://{{YOUR_STORE_URL}}/acp/products?q=headphones&vendor=Sony" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Category + Brand

Combine filters for precise results:

curl "https://{{YOUR_STORE_URL}}/acp/products?category=Electronics&vendor=Apple&max_price=300" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Multi-Brand Checkout

Users can add products from multiple vendors to a single cart:

curl -X POST "https://{{YOUR_STORE_URL}}/checkout_sessions" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}" \
  -d '{
    "items": [
      {
        "product_id": "sony_wh1000xm5",
        "quantity": 1
      },
      {
        "product_id": "apple_airpods_pro",
        "quantity": 1
      }
    ],
    "shipping_address": {
      "name": "Jane Doe",
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    }
  }'

Response:

{
  "checkout_session": {
    "id": "cs_demo_multivendor_123",
    "status": "open",
    "line_items": [
      {
        "product_id": "sony_wh1000xm5",
        "title": "Sony WH-1000XM5 Wireless Headphones",
        "unit_price": 199.99,
        "quantity": 1,
        "subtotal": 199.99
      },
      {
        "product_id": "apple_airpods_pro",
        "title": "Apple AirPods Pro (2nd Gen)",
        "unit_price": 249.99,
        "quantity": 1,
        "subtotal": 249.99
      }
    ],
    "amounts": {
      "subtotal": 449.98,
      "tax": 36.00,
      "shipping": 7.99,
      "total": 493.97,
      "currency": "USD"
    }
  }
}

Architecture

Data Model

┌─────────────────────────────────────────────────────────────────────────┐
│                              Supabase                                    │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                         products table                           │   │
│  ├──────────┬─────────────┬──────────┬─────────────┬───────────────┤   │
│  │    id    │   vendor    │  title   │  embedding  │    price      │   │
│  ├──────────┼─────────────┼──────────┼─────────────┼───────────────┤   │
│  │ sony_001 │ Sony        │ WH-1000  │ [0.1, ...]  │ 199.99        │   │
│  │ bose_001 │ Bose        │ QC45     │ [0.2, ...]  │ 179.99        │   │
│  │ appl_001 │ Apple       │ AirPods  │ [0.3, ...]  │ 249.99        │   │
│  └──────────┴─────────────┴──────────┴─────────────┴───────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        merchants table                           │   │
│  ├──────────────┬─────────────────────┬────────────────────────────┤   │
│  │  merchant_id │  name               │  webhook_url               │   │
│  ├──────────────┼─────────────────────┼────────────────────────────┤   │
│  │  sony        │ Sony Electronics    │ https://sony.com/webhooks  │   │
│  │  bose        │ Bose Corporation    │ https://bose.com/webhooks  │   │
│  └──────────────┴─────────────────────┴────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Semantic Search Across Brands

All product embeddings are stored in the same pgvector index, enabling:

Cross-brand semantic search — Find similar products regardless of vendor
Brand-agnostic recommendations — “Similar to Sony WH-1000XM5” returns Bose, Jabra options
Unified ranking — Best matches surface first, not segregated by brand

Use Cases

1. Comparison Shopping

Help users compare products across brands:

User: "Compare noise-canceling headphones from Sony and Bose"

Agent: 
I found two great options:

**Sony WH-1000XM5** - $199.99
- Industry-leading noise cancellation
- 30-hour battery life
- Multipoint connection

**Bose QuietComfort 45** - $179.99  
- Excellent comfort for long wear
- 24-hour battery life
- Adjustable ANC levels

Would you like me to add one to your cart?

2. Best Price Discovery

Find the best deal across vendors:

# Search for a specific product type
products = search_products(q="running shoes size 10")
 
# Sort by price
sorted_products = sorted(products["items"], key=lambda p: p["price"])
 
# Present options
for p in sorted_products[:3]:
    print(f"{p['vendor']}: {p['title']} - ${p['price']}")

3. Gift Shopping

Search across categories and brands:

User: "I need a gift for my dad who loves golf, budget $150"

Agent searches: q="golf gift" max_price=150

Results include:
- Titleist Pro V1 Golf Balls (Titleist) - $49.99
- Garmin Approach S12 GPS Watch (Garmin) - $149.99
- Callaway Chrome Soft Balls (Callaway) - $47.99

4. Bundle Building

Create multi-brand bundles:

{
  "items": [
    {"product_id": "sony_wh1000xm5", "quantity": 1},      // Audio
    {"product_id": "anker_powerbank", "quantity": 1},     // Accessories
    {"product_id": "apple_airpods_case", "quantity": 1}   // Protection
  ]
}

Adding Your Brand

To add your brand’s products to a Lorn AI multi-brand catalog:

1. Prepare Your Product Feed

Format your catalog according to the Product Feed Spec:

{
  "id": "your_product_001",
  "title": "Your Product Name",
  "description": "Full product description...",
  "vendor": "Your Brand",
  "price": 99.99,
  "currency": "USD",
  "availability": "in_stock",
  "images": [{"url": "https://..."}],
  "variants": [...]
}

2. Ingest Into Supabase

Products are loaded into the shared database with:

Unique IDs (prefixed with your vendor code)
Vector embeddings generated from title + description
Your brand name in the vendor field

3. Configure Webhooks

Set up your webhook endpoint to receive order notifications:

{
  "merchant_id": "your_brand",
  "webhook_url": "https://your-store.com/webhooks/lorn",
  "webhook_secret": "your_signing_secret"
}

Best Practices

Product ID Naming

Use vendor-prefixed IDs to avoid collisions:

Pattern	Example
`{vendor}_{sku}`	`sony_wh1000xm5`
`{vendor}_{category}_{id}`	`nike_running_pegasus40`

Consistent Pricing

Ensure prices are in a consistent currency or clearly labeled:

{
  "price": 199.99,
  "currency": "USD"
}

Rich Metadata

Include detailed attributes for better search matching:

{
  "category": "Electronics > Audio > Headphones",
  "tags": ["wireless", "noise-canceling", "bluetooth", "over-ear"],
  "attributes": {
    "Battery Life": ["30 hours"],
    "Connectivity": ["Bluetooth 5.0", "3.5mm jack"],
    "Features": ["Active Noise Cancellation", "Multipoint"]
  }
}

API Reference

Search with Vendor Filter

GET /acp/products?vendor={{VENDOR_NAME}}

Get Products from Multiple Vendors

GET /acp/products?q=headphones

Returns products from all vendors, ranked by relevance.

Checkout with Multiple Vendors

POST /checkout_sessions
{
  "items": [
    {"product_id": "vendor1_product", "quantity": 1},
    {"product_id": "vendor2_product", "quantity": 1}
  ]
}

Next Steps

Semantic Search — How natural language queries work
Product Feed Spec — Format your product data
Webhooks — Receive order notifications

Checkout Flow Overview