# Integration Data Checklist

What your storefront should send, to which endpoint, and **which product
feature each field unlocks**. Use this to audit or upgrade an existing custom
integration. Every row is independently shippable, and everything degrades
gracefully when a field is missing (features simply stay dark or less
precise).

If you are implementing these changes with an AI agent, point it at the MCP
server (`/mcp`). It can read every referenced doc, including the full
[API reference](v1-api-reference.md).

## The short version

| Send | To | Unlocks |
|---|---|---|
| `sku` per item | `POST /v1/items` | Human-actionable product codes in stockout alerts, replenishment, overstock and CSV exports |
| `stock_qty` per item, **updated on every stock change** | `POST /v1/items` | Stockout alerts, days-of-cover, the Replenishment page ("order 240 units by Aug 19"), the Overstock page |
| `cost` (unit cost / COGS) per item | `POST /v1/items` | Margin-aware markdowns (never discounted below cost), tied-up-capital figures on Overstock, expected margin on replenishment rows |
| `quantity` + `price` per order line | `POST /v1/orders` (live) and `/orders/upload` (history) | Unit-level demand forecasts (instead of order-line counts), revenue forecasts, price-elasticity discount suggestions |
| Real order `timestamp`s in history CSVs | `POST /orders/upload` | A usable demand forecast at all; collapsed timestamps produce a one-day spike and garbage forecasts |
| `customer_id` on orders | `POST /v1/orders` / `/orders/upload` | Customer intelligence: RFM segments, churn risk, predicted next order, CLV, the email/CRM feed |
| `session_id` (the widget's `pr_sid`) on orders | `POST /v1/orders` | Revenue attribution and A/B incrementality for anonymous shoppers |
| `quantity` + `value` on `add-to-cart`/`buy` events | `POST /v1/events` | Attribution with real line revenue; unit-aware forecasting from live tracking |
| `source` + `position` echoed on rec clicks/impressions | `POST /v1/events` | Per-source effectiveness (is AI/visual/co-purchase earning its keep?) |

## 1. Catalog pushes: `POST /v1/items` (X-API-Key)

Include on every item, and **re-push when stock changes** (a stock change
alone is a valid update; unchanged content fields don't cause re-indexing or
image re-embedding):

```json
{"items": [{
  "id": "123",
  "sku": "MUG-BG-042",
  "title": "…",
  "price": 19.9,
  "availability": "in_stock",
  "stock_qty": 42,
  "cost": 8.4,
  "product_url": "…", "image_url": "…", "categories": ["…"]
}]}
```

- `stock_qty` is the number the Demand pages run on. Without `stock_qty`
  there are no stockout alerts, no replenishment suggestions and no overstock
  report for that item. `stock_qty: 0` with no `availability` field counts as
  out of stock.
- `sku` is display-only but matters operationally: a reorder list without SKUs
  can't be handed to a supplier.
- `cost` (also accepted as `cogs`/`cost_price`) is optional and never affects
  ranking or indexing. With it, markdown suggestions respect your margin,
  Overstock shows the cash tied up in dead stock, and reorder rows carry an
  expected margin. WooCommerce stores using the Cost of Goods extension get it
  synced automatically.
- Hook your platform's stock-change events (sale, refund, manual adjustment),
  not just product edits. Batch up to 1000 items per request; debounce bursts.

## 2. Live orders: `POST /v1/orders` (X-API-Key, from your order webhook)

```json
{
  "order_id": "ORDER_1234",
  "user_id": "cust_9",
  "session_id": "s_abc123",
  "currency": "EUR",
  "items": [
    {"item_id": "123", "quantity": 12, "price": 19.9},
    {"item_id": "456", "quantity": 1, "total": 49.9}
  ]
}
```

- **`quantity` per line is not optional in spirit**: wholesale lines of 100+
  units counted as "1 order line" make demand look flat and revenue look like
  absurd unit prices. Send the real units.
- `price` is the **unit** price; `total` (line revenue) defaults to
  `price × quantity`.
- `user_id` = your platform's customer id, the same value the widget embeds get
  (`data-user-id`). This is what feeds customer intelligence: without a
  customer id there is no profile.
- `session_id` = the widget's `pr_sid` (mirror `localStorage["pr_sid"]` into a
  first-party cookie at browse time; read it in the webhook). Links anonymous
  browsing to the purchase for attribution and A/B measurement.
- Idempotent per `order_id`, so retries are safe.

## 3. Order history: `POST /orders/upload` (CSV)

Header: `order_id,item_id,customer_id,timestamp,quantity,price`.

- `timestamp` must be ISO (`2026-08-01` or full datetime). Non-ISO dates
  (e.g. `01.08.2026`) silently fall back to the import date and **destroy the
  forecast's seasonality**, so convert before uploading.
- Re-uploading a corrected file repairs the stored history in place
  (quantity/price/timestamp are overwritten by the export, lines never
  duplicate). See the [API reference](v1-api-reference.md).

## 4. Browser events: `POST /v1/events` (pk_ key)

The widgets send views, impressions and clicks automatically. Your storefront
must send commerce events itself:

```js
ProductRecs.track("add-to-cart", { item_id: "123", quantity: 2, price: 19.9 });
ProductRecs.track("buy", {
  item_id: "123", order_id: "ORDER_1234",
  quantity: 2, value: 39.8, currency: "EUR",
});
```

- `value` is the **line** revenue (unit price × units), `quantity` the units.
- One `buy` per order line, sharing the `order_id`.
- If your rendering is headless (you call `/v1/recommendations` yourself and
  render your own UI), echo each item's `source` and its display `position`
  back on `rec-impression` (index-aligned `sources`/`positions` arrays) and
  `rec-click`. Otherwise the per-source effectiveness report shows your
  traffic as "untagged".

## What you get once the data flows

- The **Demand pages (Forecast, Replenishment, Overstock)** need `stock_qty` +
  order `quantity` + real timestamps.
- **Impact page attribution & A/B incrementality** need `session_id`/
  `user_id` continuity between browsing and orders.
- **Customers page + the [customer feed](customer-feed.md)** need
  `customer_id` on orders.
- **Search Insights** needs nothing extra; it works as soon as the search
  widget is live.
