Object Reference
Complete schema reference for all Lorn AI API objects.
Product Objects
Product
Represents a product in the catalog.
{
"id": "prod_abc123",
"title": "Nike Air Zoom Pegasus 40",
"description": "Responsive cushioning meets a breathable upper...",
"vendor": "Nike",
"category": "Footwear > Running",
"price": 129.99,
"currency": "USD",
"availability": {
"status": "in_stock",
"quantity": 42
},
"tags": ["running", "athletic", "cushioned"],
"attributes": {
"Material": ["Mesh"],
"Cushioning": ["Zoom Air"]
},
"images": [
{
"url": "https://cdn.example.com/image.jpg",
"alt_text": "Product image",
"position": 1
}
],
"variants": [
{
"sku": "sku_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.92
}| Field | Type | Description |
|---|---|---|
id | string | Unique product identifier |
title | string | Product name |
description | string | Full product description |
vendor | string | Brand/manufacturer name |
category | string | Product category (hierarchical) |
price | number | Base price |
currency | string | ISO 4217 currency code |
availability | Inventory | Overall availability |
tags | string[] | Product tags |
attributes | object | Product attributes (key → values[]) |
images | Image[] | Product images |
variants | Variant[] | Product variants |
similarity_score | number? | Semantic search relevance (0-1) |
Variant
Represents a product variant (size, color, etc.).
{
"sku": "sku_black_10",
"title": "Black / Size 10",
"price": 129.99,
"currency": "USD",
"requires_shipping": true,
"taxable": true,
"weight_grams": 280,
"weight_unit": "g",
"image": "https://cdn.example.com/black.jpg",
"attributes": {
"Color": "Black",
"Size": "10"
},
"inventory": {
"status": "in_stock",
"quantity": 8
}
}| Field | Type | Description |
|---|---|---|
sku | string | Unique variant SKU |
title | string | Variant title |
price | number | Variant price |
currency | string | Currency code |
requires_shipping | boolean | Needs physical shipping |
taxable | boolean | Subject to tax |
weight_grams | number | Weight in grams |
weight_unit | string | Weight unit |
image | string | Variant-specific image URL |
attributes | object | Variant attributes (key → value) |
inventory | Inventory | Variant stock info |
Inventory
Represents stock information.
{
"status": "in_stock",
"quantity": 42,
"policy": "continue"
}| Field | Type | Values | Description |
|---|---|---|---|
status | string | in_stock, limited, out_of_stock | Availability status |
quantity | integer | Current stock count | |
policy | string | continue, deny | Behavior when out of stock |
Image
Represents a product image.
{
"url": "https://cdn.example.com/image.jpg",
"alt_text": "Product front view",
"position": 1
}| Field | Type | Description |
|---|---|---|
url | string | Image URL (HTTPS preferred) |
alt_text | string | Accessibility text |
position | integer | Display order |
Checkout Objects
CheckoutSession
Represents a shopping cart/checkout session.
{
"id": "cs_demo_abc123",
"status": "open",
"currency": "USD",
"line_items": [...],
"shipping_address": {...},
"customer": {...},
"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_abc123_secret_demo",
"created_at": "2024-01-15T10:30:00Z"
}| Field | Type | Description |
|---|---|---|
id | string | Unique session identifier |
status | string | Session status |
currency | string | Currency code |
line_items | LineItem[] | Cart items |
shipping_address | Address | Shipping destination |
customer | Customer | Customer info |
payment_method | string | Payment method |
shipping | ShippingQuote | Shipping details |
tax | TaxSummary | Tax calculation |
amounts | AmountBreakdown | Price totals |
client_secret | string | Payment intent secret |
created_at | string | Creation timestamp (ISO 8601) |
Session Status Values
| Status | Description |
|---|---|
open | Session created, accepting modifications |
not_ready_for_payment | Missing required information |
ready_for_payment | Ready to complete |
completed | Purchase finalized |
canceled | Session canceled |
LineItem
Represents an item in the cart.
{
"product_id": "prod_abc123",
"variant_sku": "sku_black_10",
"quantity": 2,
"title": "Nike Air Zoom Pegasus 40 - Black Size 10",
"unit_price": 129.99,
"currency": "USD",
"subtotal": 259.98
}| Field | Type | Description |
|---|---|---|
product_id | string | Product ID |
variant_sku | string | Variant SKU (optional) |
quantity | integer | Quantity |
title | string | Resolved product title |
unit_price | number | Price per unit |
currency | string | Currency code |
subtotal | number | unit_price × quantity |
LineItemInput
Input for creating/updating cart items.
{
"product_id": "prod_abc123",
"variant_sku": "sku_black_10",
"quantity": 2
}| Field | Type | Required | Description |
|---|---|---|---|
product_id | string | Yes | Product ID |
variant_sku | string | No | Variant SKU |
quantity | integer | No | Quantity (default: 1) |
Address
Represents a shipping or billing address.
{
"name": "Jane Doe",
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94102",
"country": "US"
}| Field | Type | Description |
|---|---|---|
name | string | Recipient name |
line1 | string | Street address line 1 |
line2 | string | Street address line 2 |
city | string | City |
state | string | State/province code |
postal_code | string | ZIP/postal code |
country | string | Country code (ISO 3166-1) |
Customer
Represents customer information.
{
"email": "jane@example.com",
"phone": "+1-555-123-4567",
"name": "Jane Doe"
}| Field | Type | Description |
|---|---|---|
email | string | Customer email |
phone | string | Customer phone |
name | string | Customer name |
ShippingQuote
Represents shipping method and cost.
{
"method": "ground",
"amount": 7.99,
"currency": "USD"
}| Field | Type | Description |
|---|---|---|
method | string | Shipping method |
amount | number | Shipping cost |
currency | string | Currency code |
TaxSummary
Represents tax calculation.
{
"rate": 0.08,
"amount": 10.40,
"currency": "USD"
}| Field | Type | Description |
|---|---|---|
rate | number | Tax rate (e.g., 0.08 = 8%) |
amount | number | Tax amount |
currency | string | Currency code |
AmountBreakdown
Represents complete price breakdown.
{
"subtotal": 129.99,
"tax": 10.40,
"shipping": 7.99,
"total": 148.38,
"currency": "USD"
}| Field | Type | Description |
|---|---|---|
subtotal | number | Sum of line item subtotals |
tax | number | Total tax |
shipping | number | Shipping cost |
total | number | subtotal + tax + shipping |
currency | string | Currency code |
Webhook Objects
WebhookEvent
Represents a webhook event.
{
"id": "evt_abc123",
"type": "order.created",
"created": "2024-01-15T10:35:00Z",
"data": {
"object": {
"id": "cs_demo_abc123",
"status": "completed",
...
}
}
}| Field | Type | Description |
|---|---|---|
id | string | Event identifier |
type | string | Event type |
created | string | Event timestamp (ISO 8601) |
data | object | Event data |
data.object | object | Event payload (e.g., checkout session) |
Event Types
| Type | Description |
|---|---|
order.created | New order placed |
order.updated | Order status changed |
order.fulfilled | Order shipped/fulfilled |
order.canceled | Order canceled |
order.refunded | Order refunded |
API Response Objects
SearchResponse
Returned by product search.
{
"items": [...],
"page": 1,
"page_size": 10,
"total": 42,
"version": "supabase-semantic",
"generated_at": "2024-01-15T10:30:00Z"
}| Field | Type | Description |
|---|---|---|
items | Product[] | Search results |
page | integer | Current page |
page_size | integer | Results per page |
total | integer | Total matching products |
version | string | Feed version |
generated_at | string | Timestamp |
CheckoutResponse
Returned by checkout operations.
{
"checkout_session": {
...
}
}| Field | Type | Description |
|---|---|---|
checkout_session | CheckoutSession | Session data |
HealthResponse
Returned by health check.
{
"status": "ok",
"supabase": "configured"
}| Field | Type | Description |
|---|---|---|
status | string | Health status |
supabase | string | Backend status |
WebhookEmitResponse
Returned by webhook emit.
{
"delivered": 200,
"signature": "t=1705312260,v1=abc123...",
"payload": {...}
}| Field | Type | Description |
|---|---|---|
delivered | integer/null | HTTP status from target |
signature | string | HMAC signature |
payload | object | Webhook payload |
Input Objects
CreateCheckoutInput
Input for creating checkout.
{
"items": [
{"product_id": "prod_abc", "variant_sku": "sku_1", "quantity": 2}
],
"shipping_address": {...},
"customer": {...},
"payment_method": "demo_card"
}| Field | Type | Required | Description |
|---|---|---|---|
items | LineItemInput[] | Yes | Cart items |
shipping_address | Address | No | Shipping address |
customer | Customer | No | Customer info |
payment_method | string | No | Payment method |
UpdateCheckoutInput
Input for updating checkout.
{
"items": [...],
"shipping_address": {...},
"customer": {...},
"payment_method": "demo_card"
}| Field | Type | Required | Description |
|---|---|---|---|
items | LineItemInput[] | No | Replace cart items |
shipping_address | Address | No | Update address |
customer | Customer | No | Update customer |
payment_method | string | No | Update payment |
WebhookEmitInput
Input for emitting webhooks.
{
"event_type": "order.created",
"checkout_session_id": "cs_demo_abc123",
"target_url": "https://...",
"payload": {...},
"signature_secret": "secret"
}| Field | Type | Required | Description |
|---|---|---|---|
event_type | string | Yes | Event type |
checkout_session_id | string | No | Include session data |
target_url | string | No | Delivery URL |
payload | object | No | Custom payload |
signature_secret | string | No | Signing secret |