Load your catalog

Item schema

item_id,name,price,category,status
PROD-001,Wireless Headphones,149.99,Electronics,active
PROD-002,Running Shoes,89.99,Footwear,active
PROD-003,Coffee Maker,59.99,Kitchen,active
PROD-004,Yoga Mat,29.99,Fitness,inactive

[
  {
    "item_id": "PROD-001",
    "item_type": "product",
    "status": "active",
    "attributes": {
      "name": "Wireless Headphones",
      "price": 149.99,
      "category": "Electronics",
      "brand": "Acoustix"
    }
  },
  {
    "item_id": "PROD-002",
    "item_type": "product",
    "status": "active",
    "attributes": { "name": "Running Shoes", "price": 89.99, "category": "Footwear" }
  }
]

In CSV, columns beyond item_id, item_type, and status are merged into attributes automatically.

User schema

user_id,email,age,interests
usr_001,alice@example.com,32,"tech,music"
usr_002,bob@example.com,45,"sports"
usr_003,carol@example.com,28,"books,travel"

Bulk import from the dashboard

Use bulk import for the initial load and any full-catalog refresh. There is no public API for file uploads — the dashboard handles auth, validation, and storage handoff for you.

For very large catalogs, split into multiple files and upload them sequentially. Each file is processed independently.

Incremental upsert

Use upsert when individual rows change — a price drops, a new product launches, a user updates their profile. Send an array of just the changed records. Existing fields not present in the payload are preserved; attributes is shallow-merged.

Both endpoints require a secret key. The body can be either a single record or an array of records:

// single record
{ "item_id": "sku-1", "status": "active" }

// or an array
[ { "item_id": "sku-1" }, { "item_id": "sku-2" } ]

curl -X POST https://ingestion.lehnz.com/api/v1/items/upsert \
  -H "X-API-KEY: lehnz_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "item_id": "PROD-001", "status": "inactive" },
    { "item_id": "PROD-005", "attributes": { "name": "New Backpack", "price": 79.99 } }
  ]'

Upserts are queued and applied within seconds. There's no upper bound on array size, but keep individual requests under 1 MB for predictable latency. For very large incremental loads (10k+ rows), prefer the dashboard bulk import above.

Lifecycle and deletion

Items and users carry a status field that tells the recommendation engine how to treat them:

status is optional on every upsert; if you omit it on a new record, the platform treats it as active.

Removing an item from your catalog

Don't delete the row — upsert it with status: "deleted":

curl -X POST https://ingestion.lehnz.com/api/v1/items/upsert \
  -H "X-API-KEY: lehnz_sk_..." \
  -H "X-Domain: commerce" \
  -H "Content-Type: application/json" \
  -d '{ "item_id": "sku-123", "status": "deleted" }'

Deleting a user (GDPR / "delete my data")

Same shape — upsert the user with status: "deleted":

curl -X POST https://ingestion.lehnz.com/api/v1/users/upsert \
  -H "X-API-KEY: lehnz_sk_..." \
  -H "X-Domain: commerce" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "user-42", "status": "deleted" }'

The platform records the deletion request as a new entry in your tenant's user ledger. Downstream processing scrubs the PII from the live state while preserving the user's identity for event-history joins (so existing analytics on past behavior still resolve).

Errors

For dashboard import errors, the UI surfaces the failing rows directly. See Errors & status codes for the full catalog.