Product Feed Specification

This guide explains how to format and deliver product data to Lorn AI for indexing and search.

Overview

The Product Feed is how merchants share their catalog with Lorn AI. A well-structured feed enables:

Accurate product discovery via semantic search
Rich product displays with images, variants, and pricing
Reliable checkout with up-to-date inventory

Feed Delivery

Delivery Methods

Method	Description
Push	POST your feed to Lorn AI’s ingestion endpoint
Pull	Host your feed at a URL for Lorn AI to fetch

File Formats

Lorn AI accepts feeds in:

JSON (recommended)
CSV
TSV
XML

Refresh Frequency

Update Type	Recommended Frequency
Full catalog	Daily
Inventory/pricing	Every 15 minutes
New products	Within 1 hour

Feed Structure

JSON Format (Recommended)

{
  "version": "1.0",
  "generated_at": "2024-01-15T10:00:00Z",
  "products": [
    {
      "id": "prod_abc123",
      "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 > Neutral",
      "price": 129.99,
      "currency": "USD",
      "availability": "in_stock",
      "inventory_quantity": 42,
      "tags": ["running", "athletic", "cushioned"],
      "images": [
        {
          "url": "https://cdn.example.com/nike-pegasus-main.jpg",
          "alt_text": "Nike Air Zoom Pegasus 40 - Side View"
        }
      ],
      "variants": [
        {
          "sku": "nike-pegasus-40-black-10",
          "title": "Black / Size 10",
          "price": 129.99,
          "attributes": {
            "Color": "Black",
            "Size": "10"
          },
          "inventory_quantity": 8
        }
      ],
      "attributes": {
        "Material": ["Mesh"],
        "Cushioning": ["Zoom Air"]
      },
      "weight": "280g",
      "brand": "Nike",
      "link": "https://your-store.com/products/nike-pegasus-40"
    }
  ]
}

Field Reference

Required Fields

Field	Type	Description	Example
`id`	string	Unique product identifier	`prod_abc123`
`title`	string	Product name (max 150 chars)	`Nike Air Zoom Pegasus 40`
`description`	string	Full description (max 5,000 chars)	`Responsive cushioning...`
`price`	number	Base price	`129.99`
`currency`	string	ISO 4217 currency code	`USD`
`availability`	string	Stock status	`in_stock`
`link`	string	Product page URL	`https://...`
`image_link`	string	Main product image URL	`https://...`

Recommended Fields

Field	Type	Description	Example
`vendor`	string	Brand/manufacturer	`Nike`
`category`	string	Category hierarchy (use `>`)	`Footwear > Running`
`tags`	string[]	Product tags	`["running", "athletic"]`
`inventory_quantity`	integer	Stock count	`42`
`brand`	string	Brand name	`Nike`
`gtin`	string	GTIN/UPC/ISBN	`123456789543`

Media Fields

Field	Type	Description
`image_link`	string	Main product image URL
`additional_image_link`	string[]	Additional images
`video_link`	string	Product video URL

Variant Fields

Field	Type	Description
`variants`	Variant[]	Product variants
`item_group_id`	string	Groups variants together

Variant Object

{
  "sku": "nike-pegasus-40-black-10",
  "title": "Black / Size 10",
  "price": 129.99,
  "currency": "USD",
  "attributes": {
    "Color": "Black",
    "Size": "10"
  },
  "inventory_quantity": 8,
  "image": "https://cdn.example.com/black-variant.jpg"
}

Pricing Fields

Field	Type	Description	Example
`price`	number	Regular price	`129.99`
`sale_price`	number	Discounted price	`99.99`
`sale_price_effective_date`	string	Sale window	`2024-01-01/2024-01-31`
`currency`	string	Currency code	`USD`

Availability Fields

Field	Type	Values
`availability`	string	`in_stock`, `out_of_stock`, `preorder`
`inventory_quantity`	integer	Stock count
`availability_date`	string	For preorder items (ISO 8601)

Shipping & Fulfillment

Field	Type	Description	Example
`shipping`	string	Format: `country:region:method:price`	`US:CA:Ground:7.99 USD`
`weight`	string	Product weight with unit	`280g`
`requires_shipping`	boolean	Needs physical delivery	`true`

Merchant Info

Field	Type	Required	Description
`seller_name`	string	Yes	Your store name
`seller_url`	string	Yes	Your store URL
`seller_privacy_policy`	string	For checkout	Privacy policy URL
`seller_tos`	string	For checkout	Terms of service URL
`return_policy`	string	Yes	Return policy URL
`return_window`	integer	Yes	Days allowed for returns

CSV Format

For CSV feeds, use these column headers:

id,title,description,price,currency,availability,link,image_link,vendor,category,tags,inventory_quantity,brand
prod_abc123,"Nike Air Zoom Pegasus 40","Responsive cushioning...",129.99,USD,in_stock,https://...,https://...,Nike,"Footwear > Running","running,athletic",42,Nike

CSV Requirements

UTF-8 encoding
First row must be headers
Quote fields containing commas
Use commas to separate multiple tags

Optimizing for Semantic Search

Semantic search uses your product data to understand meaning. Optimize for better results:

Rich Descriptions

Good:

{
  "title": "Nike Air Zoom Pegasus 40",
  "description": "The Nike Air Zoom Pegasus 40 delivers responsive cushioning and a breathable mesh upper for a comfortable ride on daily training runs. Features Zoom Air units in the forefoot for energy return, making it ideal for runners seeking a versatile everyday trainer."
}

Bad:

{
  "title": "Nike Pegasus",
  "description": "Running shoe"
}

Descriptive Tags

Include terms users might search for:

{
  "tags": [
    "running shoes",
    "daily trainer",
    "cushioned",
    "neutral",
    "breathable",
    "lightweight",
    "marathon training"
  ]
}

Hierarchical Categories

Use clear category paths:

{
  "category": "Footwear > Running > Neutral > Daily Trainers"
}

Detailed Attributes

Include searchable attributes:

{
  "attributes": {
    "Upper Material": ["Engineered Mesh"],
    "Cushioning Technology": ["Zoom Air"],
    "Drop": ["10mm"],
    "Weight": ["280g"],
    "Arch Support": ["Neutral"],
    "Terrain": ["Road"]
  }
}

Variant Best Practices

Use item_group_id to link variants:

{
  "products": [
    {
      "id": "pegasus-black-10",
      "item_group_id": "pegasus-40",
      "title": "Nike Air Zoom Pegasus 40 - Black Size 10",
      "attributes": {"Color": "Black", "Size": "10"}
    },
    {
      "id": "pegasus-white-10",
      "item_group_id": "pegasus-40",
      "title": "Nike Air Zoom Pegasus 40 - White Size 10",
      "attributes": {"Color": "White", "Size": "10"}
    }
  ]
}

Variant-Specific Images

Include images for each color:

{
  "variants": [
    {
      "sku": "pegasus-black-10",
      "attributes": {"Color": "Black"},
      "image": "https://cdn.example.com/pegasus-black.jpg"
    },
    {
      "sku": "pegasus-white-10",
      "attributes": {"Color": "White"},
      "image": "https://cdn.example.com/pegasus-white.jpg"
    }
  ]
}

Validation Rules

ID Rules

Rule	Requirement
Max length	100 characters
Uniqueness	Must be unique within your catalog
Stability	Don’t change IDs for existing products
Characters	Alphanumeric, hyphens, underscores

Price Rules

Rule	Requirement
Format	Decimal number
Minimum	Must be > 0
Sale price	Must be ≤ regular price
Currency	ISO 4217 code

Image Rules

Rule	Requirement
Format	JPEG or PNG
Protocol	HTTPS preferred
Resolution	Minimum 500x500 pixels
Accessibility	Must be publicly accessible

URL Rules

Rule	Requirement
Protocol	HTTPS required for production
Accessibility	Must return HTTP 200
Encoding	URL-encoded

Example: Complete Product

{
  "id": "prod_pegasus40",
  "gtin": "194501234567",
  "title": "Nike Air Zoom Pegasus 40",
  "description": "The Nike Air Zoom Pegasus 40 delivers responsive cushioning and a breathable mesh upper for a comfortable ride mile after mile. A widely loved favorite, the Pegasus returns with a familiar fit and updated midsole that provides more energy return.",
  "link": "https://your-store.com/products/nike-air-zoom-pegasus-40",
  "image_link": "https://cdn.your-store.com/images/pegasus40-main.jpg",
  "additional_image_link": [
    "https://cdn.your-store.com/images/pegasus40-side.jpg",
    "https://cdn.your-store.com/images/pegasus40-top.jpg"
  ],
  "vendor": "Nike",
  "brand": "Nike",
  "category": "Footwear > Running > Neutral",
  "price": 129.99,
  "sale_price": 99.99,
  "sale_price_effective_date": "2024-01-01/2024-01-31",
  "currency": "USD",
  "availability": "in_stock",
  "inventory_quantity": 42,
  "condition": "new",
  "tags": ["running", "athletic", "cushioned", "daily trainer", "neutral"],
  "attributes": {
    "Material": ["Mesh"],
    "Cushioning": ["Zoom Air"],
    "Drop": ["10mm"]
  },
  "weight": "280g",
  "item_group_id": "pegasus40",
  "variants": [
    {
      "sku": "pegasus40-black-10",
      "title": "Black / Size 10",
      "price": 129.99,
      "attributes": {"Color": "Black", "Size": "10"},
      "inventory_quantity": 8,
      "image": "https://cdn.your-store.com/images/pegasus40-black.jpg"
    },
    {
      "sku": "pegasus40-white-10",
      "title": "White / Size 10",
      "price": 129.99,
      "attributes": {"Color": "White", "Size": "10"},
      "inventory_quantity": 5,
      "image": "https://cdn.your-store.com/images/pegasus40-white.jpg"
    }
  ],
  "seller_name": "Your Store",
  "seller_url": "https://your-store.com",
  "return_policy": "https://your-store.com/returns",
  "return_window": 30,
  "shipping": "US::Ground:7.99 USD",
  "enable_search": true,
  "enable_checkout": true
}

Ingestion Process

1. Prepare Your Feed

Format your catalog according to this specification.

2. Validate

Check for required fields and proper formatting.

3. Submit

Push your feed to the ingestion endpoint or configure pull URL.

4. Monitor

Check ingestion status for any errors or warnings.

5. Test

Verify products appear correctly in search results.

Common Errors

Error	Cause	Solution
`missing_required_field`	Required field not provided	Add the missing field
`invalid_price`	Price is negative or invalid	Use positive decimal
`invalid_url`	URL doesn’t resolve	Check URL accessibility
`duplicate_id`	Same ID used twice	Ensure unique IDs
`invalid_currency`	Unknown currency code	Use ISO 4217 code