🚧

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. The exception is a manufacturing order that
  links its ingredients to the output serial numbers they went into: by default (trace_by=unit) each of those
  serial numbers counts as containing only the ingredients linked to it and those linked to none ("which bikes have
  battery C1" gives only the bike it went into; "what is in bike S2" gives only its own parts). When the trace followed
  only some of the order's serial numbers, the order names them in unit_trace. An ingredient partly used without
  a link counts in every output. trace_by=order counts every output as containing every input, e.g. to recall the
  whole order for a process issue. Orders without links trace the same either way. Several starts are traced as one,
  so unit_trace and the edges show the combined set, not which start led to which serial number: trace a serial
  number on its own for its own parts.
• A trace can miss units only where incomplete_traces names an order, where summary.is_partial is true, or,
  when tracing by unit, where an ingredient was linked to the wrong serial number.
• 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.