Lot & Batch Tracking

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €34/mo; lot expiration, batch tracking, recall workflows

Generated from docs/plan/paid/lot-batch-tracking/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid compliance module for food, pharmaceutical, and regulated merchants that tracks lot/batch numbers through inventory and orders. Enables rapid recalls by identifying all customers who received a batch, manages expiration dates, and maintains full audit trails for regulatory inspection.

The problem

A health authority issues a recall for Lot XYZ. I have 5,000 units in stock and shipped 10,000 to customers. I need to find every customer order with that lot, notify them, and document compliance. Without lot tracking, I cannot identify affected units.

What it does

• Lot/batch number assignment at receipt: when PO is received, assign lot_number, expiration_date, supplier, qty_received
• Line-item lot link: each order line_item tracks which lot was shipped
• Lot expiration checking: products from expired lots cannot be sold (checkout validation)
• Recall workflow: create recall record, query all orders with that lot, generate customer list
• Recall notification: UI to compose/send notification to affected customers with instructions
• Affected-orders report: GET /api/recalls/:id/affected-orders returns orders, customer emails, shipped dates
• Lot search endpoint: query lots by product, date range, supplier, status (in-stock, expired, all-sold, recalled)
• Lot expiration calendar: admin view of upcoming expirations by product
• Audit trail: every recall action (create, notify customers, mark resolved) logged with user and timestamp
• Bulk lot upload: CSV with lot numbers, expiration dates, supplier, quantity for fast data entry

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Deep recall automation or regulatory filing — notification is manual (staff composes message); merchants file their own compliance reports to health authorities
• Customer compliance proof or ‘proof of recall’ generation — audit log covers internal tracking; merchants provide their own evidence to regulators
• Supplier recall coordination — merchants contact suppliers directly; no two-way supplier sync
• Product destruction tracking or waste management — recall identifies affected units; merchants manage disposal independently

Data model

New tables: lots (id, product_id, lot_number, supplier_id, received_date, expiration_date, qty_received, qty_remaining, status enum(active, expired, recalled, depleted)), recalls (id, lot_id, recall_reason, created_by, created_at, recall_date, status enum(active, resolved)), recall_notifications (id, recall_id, customer_id, email, notification_date, notification_status enum(pending, sent, bounced)), affected_orders (id, recall_id, order_id, line_item_id, lot_id, customer_email, shipped_date). Orders.line_items extended with lot_id foreign key.

API

• POST /api/lots
• GET /api/lots/:id
• GET /api/lots/search?product_id=X&expiration_before=DATE
• PATCH /api/lots/:id
• POST /api/recalls
• GET /api/recalls/:id
• GET /api/recalls/:id/affected-orders
• POST /api/recalls/:id/notify-customers
• GET /api/lots/expiration-calendar
• POST /api/lots/bulk-upload

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Lot receipt form with lot_number, expiration_date, supplier picker, qty_received. Expiration calendar showing all lots, color-coded by days-to-expiration. Recall workflow: select product/lot, compose notification message, preview affected customer list, send button, status tracker. Audit log showing all recall actions and user.

The seam — why this is paid

Core owns the lot-assignment interface and audit logging. Paid owns recall SLA (rapid query of affected orders), customer notification queue, expiration enforcement, and the compliance audit trail.

Support commitment: recall SLA, customer batch notification, audit trail

Dependencies

• product module (SKU lookup)
• inventory module (qty per lot)
• order module (line_item + lot_id)
• customer module (email delivery)
• audit log system (regulatory trail)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• POST lot creates lot record with lot_number, expiration_date, and qty_received
• Expiration validation: product from expired lot cannot be added to order (checkout fails)
• Affected-orders query returns all orders with line_items.lot_id = X
• Recall notification can be previewed before sending (shows customer list and message)
• Audit log records create/notify/resolve actions with user_id and timestamp
• Bulk upload validates lot_numbers are unique before commit
• GET expiration-calendar lists all lots with expiration_date < today (red), next 30 days (yellow), future (green)

Risks

Lost lot data on sync failure (must commit before sending notification); incorrect expiration_date prevents sale of good stock (no override, only manual lot edit); recall query timeout on millions of line items; customer email bounces loop (notification_status stuck on ‘pending’); false recall (overbroad query returns wrong orders).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.