Purchase orders with traceability

A purchase order (PO) row can carry its traceability before anything arrives: the batches, serial numbers and bins the goods will be received into. A receipt that sends no traceability of its own takes these pre-assigned entries, so the warehouse only confirms quantities on delivery.

The guides in this section follow one workshop: a bike workshop buying parts for its Main warehouse (location 160012), which keeps stock in bins A-01 (512001) and A-02 (512002).

Before you start

• The items' purchase units are set on the items, so each row defaults to them.
• Batches exist before you assign them. The chain batch CH-2610 here is batch 3871301, created with POST /batches.

Quantities are in the purchase unit

A row's quantity is in its purchase unit, and so is every batch and bin entry in its traceability. Katana converts both with purchase_uom_conversion_rate:

The rate is the purchase_uom_conversion_rate sent in the same request; otherwise, when creating a row, the item's purchase unit rate, and when updating, the row's current rate. A row without a purchase unit has a rate of 1, so its quantities are in the default unit.

Serial numbers are the exception: each one is one default unit, whatever the purchase unit. Send one entry per serial number, by serial_number_id, with no quantity. 3 pairs of hub motors are 6 serial numbers.

Create the order with pre-assigned batches

Create the PO with the brake pads, then add the chain row with its batch and bin:

curl -X POST https://api.katanamrp.com/v1/purchase_orders \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"order_no": "PO-1042", "supplier_id": 2210451, "location_id": 160012, "status": "NOT_RECEIVED",
       "purchase_order_rows": [{"variant_id": 24890201, "quantity": 5, "price_per_unit": 18,
                                "purchase_uom": "pack", "purchase_uom_conversion_rate": 12}]}'

curl -X POST https://api.katanamrp.com/v1/purchase_order_rows \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"purchase_order_id": 3120415, "variant_id": 24890211, "quantity": 4, "price_per_unit": 65,
       "traceability": [{"batch_id": 3871301, "bin_location_id": 512001, "quantity": "1.5"}]}'

The chain row takes the item's purchase unit, box at 10. The response shows its traceability in boxes. The 2.5 boxes not covered by an entry appear as an untraced entry, without a batch_id:

{
  "id": 46012002,
  "purchase_order_id": 3120415,
  "variant_id": 24890211,
  "quantity": 4,
  "purchase_uom": "box",
  "purchase_uom_conversion_rate": 10,
  "traceability": [
    {"batch_id": 3871301, "serial_number_id": null, "bin_location_id": 512001, "quantity": "1.5"},
    {"batch_id": null, "serial_number_id": null, "bin_location_id": null, "quantity": "2.5"}
  ]
}

Entries together may not exceed the row quantity (422 otherwise). For an untracked item, entries with only bin_location_id and quantity pre-assign bins: the brake pads row gets [{"bin_location_id": 512002, "quantity": "5"}], all 5 packs into A-02.

Pre-assign serial numbers

Add the hub motor row (46012003, 3 pairs), then create its serial numbers on the row:

curl -X POST https://api.katanamrp.com/v1/serial_numbers \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"resource_type": "PurchaseOrderRow", "resource_id": 46012003,
       "serial_numbers": ["HM-0001", "HM-0002", "HM-0003", "HM-0004", "HM-0005", "HM-0006"]}'

Each serial number in successful has its id (7710001 to 7710006). To place them in bins, send them by id, one entry each:

curl -X PATCH https://api.katanamrp.com/v1/purchase_order_rows/46012003 \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"traceability": [
        {"serial_number_id": 7710001, "bin_location_id": 512001}, {"serial_number_id": 7710002, "bin_location_id": 512001},
        {"serial_number_id": 7710003, "bin_location_id": 512001}, {"serial_number_id": 7710004, "bin_location_id": 512001},
        {"serial_number_id": 7710005, "bin_location_id": 512002}, {"serial_number_id": 7710006, "bin_location_id": 512002}
      ]}'

Serial entries come back without a quantity: {"batch_id": null, "serial_number_id": 7710001, "bin_location_id": 512001}.

Change the traceability

On PATCH /purchase_order_rows/{id}, traceability works on the whole row:

• Omitted: the row's assignments stay as they are.
• Entries: they replace the row's assignments.
• []: clears them; the whole row is untraced.

Responses also carry batch_transactions, a deprecated batch-only view in the default unit. Read traceability instead.

Next: Receiving purchase orders.