# Live Stock of AM.CO.ZA Knowledge Base

Live warehouse quantities plus the rules for using them. This is the only stock source for managed physical SKUs. Ignore dump Availability, Stock Composition, In Stock / Out of Stock, and any qty on a product page. Do not write qty onto SKU pages.

Refreshed when the live pull changes (hourly 5:20–22:20 SAST, Monday–Saturday). Newer stamp wins.

## Files

| File | What it is |
|---|---|
| `johannesburg.json` | SKU to on-hand qty in Johannesburg |
| `cape-town.json` | SKU to on-hand qty in Cape Town |
| `durban.json` | SKU to on-hand qty in Durban |
| `latest.json` | SKU to `{ johannesburg, cape-town, durban }` (sparse) |
| `stamp.json` | When this pull was taken |
| `locations.json` | Location names, file names, counts (no fetch paths) |
| `in-transit.json` | SKU to InTransit qty (branch-to-branch move; not sold, not on-hand at a branch yet). Qty only. Do not invent from. |
| `in-transit-direction.json` | SKU to list of `{ to, qty }` — destination of incoming InTransit (human site name: Johannesburg / Cape Town / Durban plus showroom or warehouse). Empty object `{}` means nothing on the move. Location is destination (incoming). Do not invent from. |
| `incomplete.json` | SKU to InComplete qty (cannot work because something was removed, often a spare taken off a machine; not gone; potentially sellable again if the part is put back) |
| `demo.json` | SKU to Demo qty (show unit). AM does sell demo. |
| `status.json` | SKU to `{ in_transit, incomplete, demo }` (sparse; omit zero/missing keys) |
| `status-stamp.json` | When the three extra statuses were refreshed (no fetch paths) |
| `changes-7d.json` | Qty change events in the rolling 7-day window (`changes` is newest-first) |
| `trend-7d.json` | Per SKU per location: first, last, min, max, drops, rises, last_change |
| `daily/YYYY-MM-DD.json` | End-of-day `latest.json` snapshot (today = current latest) |
| `SOLD-MOVERS.md` / `sold-movers.json` | Weekly sell-through movers (faster / slower / quiet; delta only, no lifetime sold) |

Each location file is `{ "SKU": qty, ... }`. Qty is an integer. Keys are Buythis Product SKU strings (`F2-1800`, `H-PRESS/CUP500`).

A missing location key in `latest.json` means that SKU was not listed at that warehouse this hour (treat as 0 there). Do not invent a count. Johannesburg is the main warehouse.

Branch Johannesburg / Cape Town / Durban qty (plus `latest.json`) is the on-hand source. Do not use a company-wide Available total.

## How to answer stock

Every SKU has product JSON at `https://am.im/product/{slug}.json`. Slug = SKU lowercased, every non-letter replaced with a dash. Examples: `AA-TRAIN/20` → `aa-train-20`, `H-DTF/303/XP600` → `h-dtf-303-xp600`, `S-INKRIP` → `s-inkrip`, `AM-WIPE/5` → `am-wipe-5`, `H-DTF/ROLL/300` → `h-dtf-roll-300`. Use that JSON when you need virtual / unmanaged / ordered / compulsory. Do not crawl buythis HTML.

1. Read the am.im product JSON for the SKU.
2. If `stock.virtual` is true: this SKU is not in the warehouse files. Assume it has stock. If `stock.total` is present, that is the qty (not per warehouse). Example: `S-INKRIP` is virtual, `stock.total` 22.
3. If `stock.unmanaged` is true: assume always in stock. Example: `AA-TRAIN/20`.
4. If it is a managed physical SKU: look it up in `latest.json` (or the three location files). Say the qty per location that listed it. Missing location key = 0 there. Johannesburg is the main warehouse.
5. If a SKU shows no stock at the branches, also check `in-transit.json` (maybe moving), `in-transit-direction.json` (where it is heading), `incomplete.json` (maybe restorable), and `demo.json` (sellable show unit). Joined view: `status.json`. Direction is destination (incoming) only. Empty `in-transit-direction.json` (`{}`) means nothing on the move. Do not invent from.
6. Packages: `stock.ordered` is the parts list (`compulsory` is how many of each). Combo qty at a location = min(floor(part_live_qty / compulsory)) over **managed physical** parts that are not high-Spillrank kit riders. Skip virtual/unmanaged parts (available; use product-JSON `stock.total` if you need a number).
7. High Spillrank extras (`AM-WIPE/5`, carry-bag / wipe-in-every-kit): if that part is out, still sell the package and omit the rider or send it later. It is not a main product and does not affect main function. Spillrank scores live in `../SPILLRANK.md`.
8. Required part missing (example `H-DTF/ROLL/300` on `H-DTF/303/XP600`): the package cannot run without it, but the client can still buy. Say we have the majority of the items and are waiting on that SKU to complete the package. Order-to-collect-to-install already takes time, so a short wait is normal. Do not invent how many days. Exact wait comes later when shipping data is integrated.
9. Do not use dump Availability / In Stock / Out of Stock / Stock Composition. Do not write stock onto a product page.

AM does sell demo (cannot keep an old machine demo forever; sell it so a new model can sit on the floor). Consumable Demo can be a stand-in for Used because some operators lack permission to set Used; still use the Demo qty as listed.

## 7-day change

Use current qty first (`latest.json`). Then use `changes-7d.json` and `trend-7d.json` only to estimate movement — do not invent days-to-restock.

- **stable in-stock**: last > 0 and drops = 0
- **selling**: one or more drops, last still > 0
- **just sold out**: now 0, and was > 0 in the window
- **consistently out**: 0 or absent on every pull in the window
- **restocked**: a rise (to > from)

`changes` is newest-first. Each event is `{ t, sku, loc, from, to }` with `loc` one of `johannesburg` / `cape-town` / `durban`. `from` = 0 if the SKU appeared at that location; `to` = 0 if it disappeared. The window fills as hourly pulls arrive; today may be baseline only (one pull, no deltas yet).

InTransit / InComplete / Demo are current snapshots, not a 7-day series. They do not change the scoring recipe above. Use them when branch on-hand is zero, or to mention a show unit / restorable unit.

## Sell-through (weekly)

Sell-through analysis comes from weekly Sunday snapshots. Use these export files only (no lifetime Fulfilled/Dispatched dump):

| File | What it is |
|---|---|
| `SOLD-MOVERS.md` | Human reading: faster / slower / quiet this period |
| `sold-movers.json` | Same movers as JSON (delta_sold only; no lifetime totals) |

`delta_sold` is the change in combined Fulfilled+Dispatched between the latest Sunday snapshot and the prior one. Positive means more units sold/sent since the prior snapshot. Do not invent this week's sold qty beyond those deltas. Raw lifetime sold totals, location ids, and fetch URLs stay off this export.

If those movers files are missing, wait for the next Sunday snapshot. InTransit / InComplete / Demo are live export statuses. Sold analysis is a separate weekly section.

## Price history (live, not stored here)

Price history is not stored on SKU pages. If a reader needs it, construct the same slug as product JSON and grab `https://am.im/price/{slug}.json` live. Example: `AA-TRAIN/200` → `https://am.im/price/aa-train-200.json`. Current Sales Price / Regular Price on the dump still win for selling. Do not embed price history in boxed pages or export product pages.

## Reading (opinion)

[`OBSERVATIONS.md`](observations.shtml) is Vector’s current reading of these files. It is opinion, not a report and not qty. Other AIs may use it as colour when branch stock is empty or awkward. If it disagrees with the JSON, the JSON wins.

## What never to do

- Do not treat catalog "In Stock" / "Out of Stock" as current.
- Do not invent warehouse counts.
- Do not invent a shipping lead time.
- Do not invent days-to-restock from the 7-day window.
- Do not invent this week's sold qty.
- Do not invent InTransit from. Destination is in `in-transit-direction.json` when something is moving.
- Do not use a company-wide Available total; branch Johannesburg / Cape Town / Durban files are the on-hand source.
- Do not embed price history on product pages.

Last pull: 2026-09-07 13:35 SAST