Quickstart Guide

Get up and running with Lorn AI in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

Your Lorn AI API key
Your store’s base URL (e.g., https://your-store.lorn.ai)

Don’t have these yet? Contact us to get started.

Step 1: Test Your Connection

Verify your API access with a health check:

curl "https://{{YOUR_STORE_URL}}/health"

Expected Response:

{
  "status": "ok",
  "supabase": "configured"
}

Step 2: Search for Products

Make your first semantic search query:

curl "https://{{YOUR_STORE_URL}}/acp/products?q=comfortable+running+shoes" \
  -H "Accept: application/json" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Response:

{
  "items": [
    {
      "id": "prod_running_001",
      "title": "Nike Air Zoom Pegasus 40",
      "description": "Responsive cushioning meets a breathable upper for a comfortable ride mile after mile.",
      "vendor": "Nike",
      "category": "Footwear > Running",
      "price": 129.99,
      "currency": "USD",
      "availability": {
        "status": "in_stock",
        "quantity": 42
      },
      "tags": ["running", "athletic", "cushioned"],
      "images": [
        {
          "url": "https://cdn.example.com/nike-pegasus-40.jpg",
          "alt_text": "Nike Air Zoom Pegasus 40"
        }
      ],
      "variants": [
        {
          "sku": "nike-pegasus-40-black-10",
          "title": "Black / Size 10",
          "price": 129.99,
          "currency": "USD",
          "attributes": {
            "Color": "Black",
            "Size": "10"
          },
          "inventory": {
            "status": "in_stock",
            "quantity": 8
          }
        }
      ],
      "similarity_score": 0.89
    }
  ],
  "page": 1,
  "page_size": 10,
  "total": 1,
  "version": "supabase-semantic",
  "generated_at": "2024-01-15T10:30:00Z"
}

Note: The similarity_score (0-1) indicates how well the product matches your query. Higher is better.

Step 3: Get Product Details

Fetch complete details for a specific product:

curl "https://{{YOUR_STORE_URL}}/acp/products/prod_running_001" \
  -H "Accept: application/json" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

This returns the full product with all variants, images, and inventory.

Step 4: Create a Checkout Session

Add items to a shopping 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": "prod_running_001",
        "variant_sku": "nike-pegasus-40-black-10",
        "quantity": 1
      }
    ],
    "shipping_address": {
      "name": "Jane Doe",
      "line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    },
    "customer": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    }
  }'

Response:

{
  "checkout_session": {
    "id": "cs_demo_a1b2c3d4e5",
    "status": "open",
    "currency": "USD",
    "line_items": [
      {
        "product_id": "prod_running_001",
        "variant_sku": "nike-pegasus-40-black-10",
        "quantity": 1,
        "title": "Nike Air Zoom Pegasus 40",
        "unit_price": 129.99,
        "currency": "USD",
        "subtotal": 129.99
      }
    ],
    "shipping_address": {
      "name": "Jane Doe",
      "line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    },
    "customer": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    },
    "payment_method": "demo_card",
    "shipping": {
      "method": "ground",
      "amount": 7.99,
      "currency": "USD"
    },
    "tax": {
      "rate": 0.08,
      "amount": 10.40,
      "currency": "USD"
    },
    "amounts": {
      "subtotal": 129.99,
      "tax": 10.40,
      "shipping": 7.99,
      "total": 148.38,
      "currency": "USD"
    },
    "client_secret": "pi_demo_cs_demo_a1b2c3d4e5_secret_demo",
    "created_at": "2024-01-15T10:35:00Z"
  }
}

Step 5: Complete the Purchase

Finalize the checkout:

curl -X POST "https://{{YOUR_STORE_URL}}/checkout_sessions/cs_demo_a1b2c3d4e5/complete" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Response:

{
  "checkout_session": {
    "id": "cs_demo_a1b2c3d4e5",
    "status": "completed",
    "currency": "USD",
    "line_items": [...],
    "amounts": {
      "subtotal": 129.99,
      "tax": 10.40,
      "shipping": 7.99,
      "total": 148.38,
      "currency": "USD"
    },
    "created_at": "2024-01-15T10:35:00Z"
  }
}

🎉 Congratulations! You’ve completed your first purchase flow with Lorn AI.

Quick Reference

Base URL

https://{{YOUR_STORE_URL}}

Required Headers

Header	Value	Description
`Accept`	`application/json`	Response format
`Content-Type`	`application/json`	Request body format (POST/PATCH)
`X-ACP-API-Key`	`{{YOUR_API_KEY}}`	Authentication

Common Endpoints

Method	Endpoint	Description
`GET`	`/health`	Health check
`GET`	`/acp/products`	Search products
`GET`	`/acp/products/{id}`	Get product details
`POST`	`/checkout_sessions`	Create checkout
`PATCH`	`/checkout_sessions/{id}`	Update checkout
`POST`	`/checkout_sessions/{id}/complete`	Complete purchase

What’s Next?

Now that you’ve made your first API calls, explore:

Authentication — Learn about API keys and request signing
Products API Reference — All search parameters and filters
Checkout API Reference — Full cart management
Building a Shopping Agent — Create an AI shopping assistant

Troubleshooting

”Supabase not configured” error

{
  "detail": "Supabase not configured. Set SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, and OPENAI_API_KEY."
}

Solution: Ensure your Lorn AI instance has the required environment variables set. Contact support if using managed hosting.

Empty search results

If your search returns no items:

Try a broader query (remove filters)
Check that products exist in your catalog
Verify your API key has access to the merchant’s catalog

”Product not found” on checkout

Ensure the product_id and variant_sku values match exactly what was returned from the search API.

Demo Mode

During development, Lorn AI operates in demo mode:

No real payments are processed
Tax rate is fixed at 8%
Shipping is fixed at $7.99
Payment method defaults to demo_card

This allows you to test the full checkout flow without any financial transactions.

Introduction Authentication