docsResourcesObject Reference

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
}
FieldTypeDescription
idstringUnique product identifier
titlestringProduct name
descriptionstringFull product description
vendorstringBrand/manufacturer name
categorystringProduct category (hierarchical)
pricenumberBase price
currencystringISO 4217 currency code
availabilityInventoryOverall availability
tagsstring[]Product tags
attributesobjectProduct attributes (key → values[])
imagesImage[]Product images
variantsVariant[]Product variants
similarity_scorenumber?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
  }
}
FieldTypeDescription
skustringUnique variant SKU
titlestringVariant title
pricenumberVariant price
currencystringCurrency code
requires_shippingbooleanNeeds physical shipping
taxablebooleanSubject to tax
weight_gramsnumberWeight in grams
weight_unitstringWeight unit
imagestringVariant-specific image URL
attributesobjectVariant attributes (key → value)
inventoryInventoryVariant stock info

Inventory

Represents stock information.

{
  "status": "in_stock",
  "quantity": 42,
  "policy": "continue"
}
FieldTypeValuesDescription
statusstringin_stock, limited, out_of_stockAvailability status
quantityintegerCurrent stock count
policystringcontinue, denyBehavior when out of stock

Image

Represents a product image.

{
  "url": "https://cdn.example.com/image.jpg",
  "alt_text": "Product front view",
  "position": 1
}
FieldTypeDescription
urlstringImage URL (HTTPS preferred)
alt_textstringAccessibility text
positionintegerDisplay 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"
}
FieldTypeDescription
idstringUnique session identifier
statusstringSession status
currencystringCurrency code
line_itemsLineItem[]Cart items
shipping_addressAddressShipping destination
customerCustomerCustomer info
payment_methodstringPayment method
shippingShippingQuoteShipping details
taxTaxSummaryTax calculation
amountsAmountBreakdownPrice totals
client_secretstringPayment intent secret
created_atstringCreation timestamp (ISO 8601)

Session Status Values

StatusDescription
openSession created, accepting modifications
not_ready_for_paymentMissing required information
ready_for_paymentReady to complete
completedPurchase finalized
canceledSession 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
}
FieldTypeDescription
product_idstringProduct ID
variant_skustringVariant SKU (optional)
quantityintegerQuantity
titlestringResolved product title
unit_pricenumberPrice per unit
currencystringCurrency code
subtotalnumberunit_price × quantity

LineItemInput

Input for creating/updating cart items.

{
  "product_id": "prod_abc123",
  "variant_sku": "sku_black_10",
  "quantity": 2
}
FieldTypeRequiredDescription
product_idstringYesProduct ID
variant_skustringNoVariant SKU
quantityintegerNoQuantity (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"
}
FieldTypeDescription
namestringRecipient name
line1stringStreet address line 1
line2stringStreet address line 2
citystringCity
statestringState/province code
postal_codestringZIP/postal code
countrystringCountry code (ISO 3166-1)

Customer

Represents customer information.

{
  "email": "jane@example.com",
  "phone": "+1-555-123-4567",
  "name": "Jane Doe"
}
FieldTypeDescription
emailstringCustomer email
phonestringCustomer phone
namestringCustomer name

ShippingQuote

Represents shipping method and cost.

{
  "method": "ground",
  "amount": 7.99,
  "currency": "USD"
}
FieldTypeDescription
methodstringShipping method
amountnumberShipping cost
currencystringCurrency code

TaxSummary

Represents tax calculation.

{
  "rate": 0.08,
  "amount": 10.40,
  "currency": "USD"
}
FieldTypeDescription
ratenumberTax rate (e.g., 0.08 = 8%)
amountnumberTax amount
currencystringCurrency code

AmountBreakdown

Represents complete price breakdown.

{
  "subtotal": 129.99,
  "tax": 10.40,
  "shipping": 7.99,
  "total": 148.38,
  "currency": "USD"
}
FieldTypeDescription
subtotalnumberSum of line item subtotals
taxnumberTotal tax
shippingnumberShipping cost
totalnumbersubtotal + tax + shipping
currencystringCurrency 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",
      ...
    }
  }
}
FieldTypeDescription
idstringEvent identifier
typestringEvent type
createdstringEvent timestamp (ISO 8601)
dataobjectEvent data
data.objectobjectEvent payload (e.g., checkout session)

Event Types

TypeDescription
order.createdNew order placed
order.updatedOrder status changed
order.fulfilledOrder shipped/fulfilled
order.canceledOrder canceled
order.refundedOrder 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"
}
FieldTypeDescription
itemsProduct[]Search results
pageintegerCurrent page
page_sizeintegerResults per page
totalintegerTotal matching products
versionstringFeed version
generated_atstringTimestamp

CheckoutResponse

Returned by checkout operations.

{
  "checkout_session": {
    ...
  }
}
FieldTypeDescription
checkout_sessionCheckoutSessionSession data

HealthResponse

Returned by health check.

{
  "status": "ok",
  "supabase": "configured"
}
FieldTypeDescription
statusstringHealth status
supabasestringBackend status

WebhookEmitResponse

Returned by webhook emit.

{
  "delivered": 200,
  "signature": "t=1705312260,v1=abc123...",
  "payload": {...}
}
FieldTypeDescription
deliveredinteger/nullHTTP status from target
signaturestringHMAC signature
payloadobjectWebhook 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"
}
FieldTypeRequiredDescription
itemsLineItemInput[]YesCart items
shipping_addressAddressNoShipping address
customerCustomerNoCustomer info
payment_methodstringNoPayment method

UpdateCheckoutInput

Input for updating checkout.

{
  "items": [...],
  "shipping_address": {...},
  "customer": {...},
  "payment_method": "demo_card"
}
FieldTypeRequiredDescription
itemsLineItemInput[]NoReplace cart items
shipping_addressAddressNoUpdate address
customerCustomerNoUpdate customer
payment_methodstringNoUpdate payment

WebhookEmitInput

Input for emitting webhooks.

{
  "event_type": "order.created",
  "checkout_session_id": "cs_demo_abc123",
  "target_url": "https://...",
  "payload": {...},
  "signature_secret": "secret"
}
FieldTypeRequiredDescription
event_typestringYesEvent type
checkout_session_idstringNoInclude session data
target_urlstringNoDelivery URL
payloadobjectNoCustom payload
signature_secretstringNoSigning secret