docsAPI ReferenceOverview

API Reference Overview

This section provides complete documentation for all Lorn AI API endpoints.

Base URL

EnvironmentBase URL
Productionhttps://{{YOUR_STORE_URL}}
Sandboxhttps://sandbox.{{YOUR_STORE_URL}}
Local Developmenthttp://localhost:8000

All API requests should be made to your assigned base URL.

Authentication

Include your API key in the X-ACP-API-Key header:

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

See Authentication for details on API keys, request signing, and security.

Request Format

Headers

HeaderRequiredDescription
X-ACP-API-KeyYesYour API authentication key
AcceptRecommendedapplication/json
Content-TypeFor POST/PATCHapplication/json
Idempotency-KeyRecommendedUnique key for idempotent operations

Request Body

All POST and PATCH requests accept JSON bodies:

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_123", "quantity": 1}]}'

Response Format

All responses are JSON with consistent structure.

Success Response

{
  "items": [...],
  "page": 1,
  "page_size": 10,
  "total": 42
}

Error Response

{
  "detail": "Error message describing what went wrong"
}

Or for structured errors:

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_field",
    "message": "The 'items' field is required",
    "param": "items"
  }
}

HTTP Status Codes

CodeDescription
200Success
201Created (for POST creating resources)
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
404Not Found - Resource doesn’t exist
405Method Not Allowed - Invalid operation
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service Unavailable - Backend not configured

Pagination

List endpoints support pagination:

ParameterTypeDefaultDescription
pageinteger1Page number (1-indexed)
page_sizeinteger10Results per page (max: 100)

Example

curl "https://{{YOUR_STORE_URL}}/acp/products?page=2&page_size=20" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Response

{
  "items": [...],
  "page": 2,
  "page_size": 20,
  "total": 150
}

Rate Limits

TierRequests/MinuteRequests/Day
Sandbox601,000
Production600100,000
EnterpriseCustomCustom

Rate limit headers are included in responses:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1705312260

API Versioning

The current API version is 2025-01-01. Include the version header for stability:

curl "https://{{YOUR_STORE_URL}}/acp/products" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}" \
  -H "API-Version: 2025-01-01"

Endpoints Summary

Product Discovery

MethodEndpointDescription
GET/acp/productsSearch products
GET/acp/products/searchSearch products (alias)
GET/acp/products/{id}Get product by ID

Checkout Sessions

MethodEndpointDescription
POST/checkout_sessionsCreate checkout
GET/checkout_sessions/{id}Get checkout state
PATCH/checkout_sessions/{id}Update checkout
POST/checkout_sessions/{id}/completeComplete purchase
POST/checkout_sessions/{id}/cancelCancel checkout

Webhooks

MethodEndpointDescription
POST/webhooks/emitEmit webhook event

Utilities

MethodEndpointDescription
GET/healthHealth check

SDKs & Libraries

Official examples are available in:

Testing

Sandbox Environment

Use the sandbox environment for development and testing:

  • No real payments processed
  • Fixed tax rate (8%) and shipping ($7.99)
  • Test data that can be freely modified

Health Check

Verify connectivity:

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

Expected response:

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

Support

Multi-Brand CatalogsProducts