Lot and serial traceability

Lots, serials, reservations, quarantine, and NCRs — answering “which units are affected and where are they” in minutes.

Traceability answers one question under pressure: a defect or recall exists — which units are affected, and where is every one of them? The answer is only fast if identity was captured at every handoff. This guide is the discipline, and the payoff.

Two granularities:

	Tracks	Use for
Lot	A batch (lot_2026_07_A)	Anything made or received together — consumables, food, cosmetics, components
Serial	One physical unit	Warrantied goods, electronics, anything an individual unit’s history matters for

Capture at receipt

Lots and serials are created when goods arrive:

curl -X POST https://api.stateset.com/api/v1/lots \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "sku": "CREAM-50ML", "lot_number": "L2026-07-A", "quantity": 480, "expires_at": "2027-07-01" }'

curl -X POST https://api.stateset.com/api/v1/serials \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "sku": "DEVICE-X", "serial_number": "SN-4419-2210" }'

Identity capture is all-or-nothing per SKU. A lot-tracked product with some untracked units has no recall story — the untracked units are exactly the ones you cannot find. If you turn tracking on, backfill or quarantine the untracked stock.

Reserve and consume

Reservations tie identity to demand before the goods move — an order, a work order:

curl -X POST https://api.stateset.com/api/v1/lots/{id}/reserve \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "quantity": 24, "reference": "wo_1201" }'

# release if the demand goes away:
curl -X POST https://api.stateset.com/api/v1/lots/reservations/{reservation_id}/release \
  -H "Authorization: Bearer $STATESET_API_KEY"

Consumption (POST /api/v1/lots/{id}/consume) records the lot into what it became — a production batch records which component lots went into which finished lot, which is the link a recall walks. Serials mirror the moves: /{id}/ship on the way out, /{id}/return on the way back, /{id}/scrap at end of life.

Expiry

curl "https://api.stateset.com/api/v1/lots/expiring?within_days=60" \
  -H "Authorization: Bearer $STATESET_API_KEY"

Run it weekly. Expiring stock found at 60 days is a promotion; found at 5 days it is a write-off. Pickers consuming oldest-first only works if lot dates were captured at receipt — see the warning above.

Quarantine and quality

The moment a lot is suspect:

curl -X POST https://api.stateset.com/api/v1/lots/{id}/quarantine \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "reason": "customer reports of separation, NCR-88" }'

Quarantined stock is off sellable inventory immediately — picks stop finding it while you investigate, not after. The investigation itself is a quality workflow: an inspection (POST /api/v1/quality/inspections, then /start, /results, /complete) and an NCR (POST /api/v1/quality/ncrs) whose disposition (/{id}/disposition) decides the lot’s fate — release (POST /api/v1/lots/{id}/release-quarantine), rework, return to vendor, or scrap.

The recall drill

When it’s real, the sequence is four reads and one write:

1. GET /api/v1/lots?lot_number=L2026-07-A — the lot, its remaining quantity
2. GET /api/v1/warehouse-locations/{id}/inventory — where the on-hand units sit
3. Shipped units — the lot’s consumption and shipment history names the orders, which names the customers
4. POST /api/v1/lots/{id}/quarantine — stop further movement, then work the list

Run this drill on a fake defect once a quarter and time it. The gap between “minutes” and “days” is entirely determined by capture discipline at receipt — and it is much cheaper to discover a hole in the drill than in the recall.

Related

• Receiving and put-away — where capture happens
• Returns and RTV — defective units coming back
• Manufacturing quality reference