cURL Examples

Complete cURL examples for all Lorn AI API endpoints.

Setup

Set your environment variables:

export LORN_BASE_URL="https://{{YOUR_STORE_URL}}"
export LORN_API_KEY="{{YOUR_API_KEY}}"

Health Check

curl "${LORN_BASE_URL}/health"

Response:

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

Product Discovery

Search Products

Basic semantic search:

curl "${LORN_BASE_URL}/acp/products?q=running+shoes" \
  -H "Accept: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

With filters:

curl "${LORN_BASE_URL}/acp/products?q=wireless+headphones&min_price=50&max_price=200&page_size=5" \
  -H "Accept: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

Category filter:

curl "${LORN_BASE_URL}/acp/products?category=Electronics&page=1&page_size=20" \
  -H "Accept: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

Get Product Details

curl "${LORN_BASE_URL}/acp/products/{{PRODUCT_ID}}" \
  -H "Accept: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

Checkout Sessions

Create Checkout

Minimal (items only):

curl -X POST "${LORN_BASE_URL}/checkout_sessions" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "items": [
      {
        "product_id": "{{PRODUCT_ID}}",
        "quantity": 1
      }
    ]
  }'

With variant:

curl -X POST "${LORN_BASE_URL}/checkout_sessions" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "items": [
      {
        "product_id": "{{PRODUCT_ID}}",
        "variant_sku": "{{VARIANT_SKU}}",
        "quantity": 2
      }
    ]
  }'

Complete with all details:

curl -X POST "${LORN_BASE_URL}/checkout_sessions" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "items": [
      {
        "product_id": "{{PRODUCT_ID}}",
        "variant_sku": "{{VARIANT_SKU}}",
        "quantity": 1
      }
    ],
    "shipping_address": {
      "name": "Jane Doe",
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    },
    "customer": {
      "email": "jane@example.com",
      "phone": "+1-555-123-4567",
      "name": "Jane Doe"
    }
  }'

Get Checkout Session

curl "${LORN_BASE_URL}/checkout_sessions/{{SESSION_ID}}" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

Update Checkout Session

Update shipping address:

curl -X PATCH "${LORN_BASE_URL}/checkout_sessions/{{SESSION_ID}}" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "shipping_address": {
      "name": "Jane Doe",
      "line1": "456 Oak Avenue",
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "90001",
      "country": "US"
    }
  }'

Update cart items:

curl -X PATCH "${LORN_BASE_URL}/checkout_sessions/{{SESSION_ID}}" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "items": [
      {"product_id": "{{PRODUCT_ID}}", "quantity": 3}
    ]
  }'

Update customer:

curl -X PATCH "${LORN_BASE_URL}/checkout_sessions/{{SESSION_ID}}" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "customer": {
      "email": "new.email@example.com",
      "name": "Jane Smith"
    }
  }'

Complete Checkout

curl -X POST "${LORN_BASE_URL}/checkout_sessions/{{SESSION_ID}}/complete" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

Cancel Checkout

curl -X POST "${LORN_BASE_URL}/checkout_sessions/{{SESSION_ID}}/cancel" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

Webhooks

Emit Webhook

With checkout session:

curl -X POST "${LORN_BASE_URL}/webhooks/emit" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "event_type": "order.created",
    "checkout_session_id": "{{SESSION_ID}}",
    "target_url": "https://your-app.com/webhooks/lorn"
  }'

With custom payload:

curl -X POST "${LORN_BASE_URL}/webhooks/emit" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "event_type": "order.fulfilled",
    "payload": {
      "order_id": "order_123",
      "tracking_number": "1Z999AA10123456784"
    },
    "target_url": "https://your-app.com/webhooks/lorn"
  }'

Test without delivery:

curl -X POST "${LORN_BASE_URL}/webhooks/emit" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d '{
    "event_type": "order.created",
    "checkout_session_id": "{{SESSION_ID}}"
  }'

Complete Purchase Flow

Full example script:

#!/bin/bash
 
LORN_BASE_URL="https://{{YOUR_STORE_URL}}"
LORN_API_KEY="{{YOUR_API_KEY}}"
 
echo "=== Step 1: Search for products ==="
PRODUCTS=$(curl -s "${LORN_BASE_URL}/acp/products?q=running+shoes&max_price=100" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}")
 
PRODUCT_ID=$(echo $PRODUCTS | jq -r '.items[0].id')
echo "Found product: $PRODUCT_ID"
 
echo -e "\n=== Step 2: Get product details ==="
PRODUCT=$(curl -s "${LORN_BASE_URL}/acp/products/${PRODUCT_ID}" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}")
 
VARIANT_SKU=$(echo $PRODUCT | jq -r '.variants[0].sku')
echo "Selected variant: $VARIANT_SKU"
 
echo -e "\n=== Step 3: Create checkout ==="
CHECKOUT=$(curl -s -X POST "${LORN_BASE_URL}/checkout_sessions" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -d "{
    \"items\": [{\"product_id\": \"${PRODUCT_ID}\", \"variant_sku\": \"${VARIANT_SKU}\", \"quantity\": 1}],
    \"shipping_address\": {
      \"name\": \"Jane Doe\",
      \"line1\": \"123 Main St\",
      \"city\": \"San Francisco\",
      \"state\": \"CA\",
      \"postal_code\": \"94102\",
      \"country\": \"US\"
    },
    \"customer\": {\"email\": \"jane@example.com\"}
  }")
 
SESSION_ID=$(echo $CHECKOUT | jq -r '.checkout_session.id')
TOTAL=$(echo $CHECKOUT | jq -r '.checkout_session.amounts.total')
echo "Session created: $SESSION_ID"
echo "Total: \$$TOTAL"
 
echo -e "\n=== Step 4: Complete purchase ==="
ORDER=$(curl -s -X POST "${LORN_BASE_URL}/checkout_sessions/${SESSION_ID}/complete" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}")
 
STATUS=$(echo $ORDER | jq -r '.checkout_session.status')
echo "Order status: $STATUS"
echo "Order completed!"

Tips

Pretty Print JSON

Add | jq . for readable output:

curl "${LORN_BASE_URL}/acp/products?q=shoes" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" | jq .

Save Response to File

curl "${LORN_BASE_URL}/acp/products?q=shoes" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}" \
  -o products.json

Verbose Mode (Debugging)

curl -v "${LORN_BASE_URL}/acp/products" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

Include Response Headers

curl -i "${LORN_BASE_URL}/acp/products" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}"

Error Handling

Check HTTP status:

HTTP_CODE=$(curl -s -o response.json -w "%{http_code}" \
  "${LORN_BASE_URL}/acp/products/invalid_id" \
  -H "X-ACP-API-Key: ${LORN_API_KEY}")
 
if [ "$HTTP_CODE" -eq 200 ]; then
  echo "Success"
  cat response.json
elif [ "$HTTP_CODE" -eq 404 ]; then
  echo "Not found"
elif [ "$HTTP_CODE" -eq 401 ]; then
  echo "Unauthorized - check API key"
else
  echo "Error: HTTP $HTTP_CODE"
  cat response.json
fi

Go Object Reference