🚧

Beta — subject to change. This endpoint is publicly available, but its request/response shape may evolve before General Availability as we incorporate early feedback.

Follows batches (lots) and serial numbers through every document in both
directions: back to the suppliers and purchase orders they came from, and forward through manufacturing orders and
outsourced purchase orders to the sales orders and customers that received them, with the stock adjustments that
added or removed them and the stock left of everything reached. Several batches and serial numbers given together
are traced as one combined trace.

Where each answer is

• Who received it, for a recall ("our supplier says flour batch FL-0815 is bad, who got bread made from it?"):
  recall.shipped_sales_orders lists each sales order with the customer's email, phone and ship-to address and the
  batches or serial numbers it shipped. recall.open_orders lists the orders that have traced stock assigned and can
  still be stopped. recall.stock_on_hand lists what is left to quarantine, per location and bin.
• Where it came from, for a complaint ("where did the motor in this e-bike come from?"): trace the e-bike's serial
  number. recall.purchase_orders lists the purchase orders and suppliers of everything it was made from. For one
  component, find its node (direction: upstream): issued_by on the node's traceability names its
  supplier, and the edges into the node lead to its purchase order.
• One step back and one step forward: pass max_depth=0. It returns the documents the starts themselves moved
  on: the purchase orders that received them, the manufacturing orders that used or made them and the sales orders
  that shipped them, but not what those manufacturing orders made.
• Everything made or received in a period ("every batch of this bread made last week"): list them per variant with
  GET /traceability/added_to_stock and trace them together here. To narrow to one production line or machine, keep
  those whose manufacturing order ran on it (GET /manufacturing_order_operation_rows gives each order's
  resource_id).
• Mock recall or audit: summary has the counts and the stock at risk. include_movements=true adds every
  completed movement of each batch and serial number to its node, for a timeline and a mass balance.

How to read it

• Every output of a manufacturing order or outsourced purchase order counts as containing every input the order
  used, so a recall can include more units than were really affected. It can miss units only where
  incomplete_traces names an order or summary.is_partial is true.
• recall and summary answer most questions directly. The graph behind them is nodes (batches, serial
  numbers and serial groups) and documents (orders and stock adjustments, linked by edges in the direction
  the stock flowed; stock transfers are listed without edges).
• Quantities are decimal strings in the unit of measure of their variant.

Finding the ids: a batch id is the batch_id from
GET /batch_stocks?batch_number={exact batch number}&include_empty=true (one row per location; the same number
can exist on several variants, so check variant_id). A serial number id is the id from
GET /serial_numbers?resource_type={type}&resource_id={id} for a document it is on, e.g.
resource_type=SalesOrderRow with the sales order row id.