Running a stocktake

A stocktake counts what is on the shelves and corrects stock to match. This guide counts aisle A of the bike workshop after the deliveries in Receiving purchase orders: at location 160012, bin A-02 (512002) holds 60 pcs of brake pads (24890201) and 25 pcs of chain (24890211) batch CH-2611 (3871302), and bin A-01 (512001) holds 15 pcs of chain batch CH-2610 (3871301).

A stocktake moves through four statuses: NOT_STARTED → IN_PROGRESS → COUNTED → COMPLETED. Each status change runs in the background: the PATCH returns 204, and status_update_in_progress stays true until it is done. Wait for it to turn false before the next change to the stocktake or its rows. Statuses go in order: from NOT_STARTED, the next one is IN_PROGRESS.

Create the stocktake and its rows

curl -X POST https://api.katanamrp.com/v1/stocktakes \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"stocktake_number": "STK-31", "location_id": 160012, "reason": "Monthly count of aisle A"}'

The new stocktake, 7202001, is NOT_STARTED. Add one row per item, batch and bin you will count:

curl -X POST https://api.katanamrp.com/v1/stocktake_rows \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"stocktake_id": 7202001, "stocktake_rows": [
        {"variant_id": 24890201, "bin_location_id": 512002},
        {"variant_id": 24890211, "batch_id": 3871301, "bin_location_id": 512001},
        {"variant_id": 24890211, "batch_id": 3871302, "bin_location_id": 512002}
      ]}'

A batch-tracked item takes a batch_id on every row; one row per batch and bin.

Start counting

curl -X PATCH https://api.katanamrp.com/v1/stocktakes/7202001 \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"status": "IN_PROGRESS"}'

Starting records each row's stock at that moment in in_stock_quantity: what Katana expects on the shelf. Poll the stocktake until the change is done:

curl "https://api.katanamrp.com/v1/stocktakes?ids=7202001" -H "Authorization: Bearer $KATANA_API_KEY"

Enter the counts

Count each shelf and enter what you find, row by row:

curl -X PATCH https://api.katanamrp.com/v1/stocktake_rows/8830001 \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"counted_quantity": 60}'

The chain rows get 14 (CH-2610, one piece missing) and 25 (CH-2611). Rows you leave without a count are left out of the stock correction, unless set_remaining_items_as_counted is true on the stocktake (set it with PATCH /stocktakes/{id}): then an empty row counts as 0 and its stock is written off.

Mark it counted

curl -X PATCH https://api.katanamrp.com/v1/stocktakes/7202001 \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"status": "COUNTED"}'

Each row now has its discrepancy_quantity: counted minus in_stock_quantity. Katana also rechecks each row's stock as it is now, in rechecked_in_stock_quantity, and the time in the stocktake's stock_rechecked_at:

curl "https://api.katanamrp.com/v1/stocktake_rows?stocktake_ids=7202001" -H "Authorization: Bearer $KATANA_API_KEY"

{
  "data": [
    {
      "id": 8830001,
      "variant_id": 24890201,
      "batch_id": null,
      "bin_location_id": 512002,
      "in_stock_quantity": "60.00000000000000000000",
      "counted_quantity": 60,
      "discrepancy_quantity": "0.00000000000000000000",
      "rechecked_in_stock_quantity": "60.00000000000000000000"
    },
    {
      "id": 8830002,
      "variant_id": 24890211,
      "batch_id": 3871301,
      "bin_location_id": 512001,
      "in_stock_quantity": "15.00000000000000000000",
      "counted_quantity": 14,
      "discrepancy_quantity": "-1.00000000000000000000",
      "rechecked_in_stock_quantity": "15.00000000000000000000"
    },
    {
      "id": 8830003,
      "variant_id": 24890211,
      "batch_id": 3871302,
      "bin_location_id": 512002,
      "in_stock_quantity": "25.00000000000000000000",
      "counted_quantity": 25,
      "discrepancy_quantity": "0.00000000000000000000",
      "rechecked_in_stock_quantity": "25.00000000000000000000"
    }
  ]
}

Counts can still be corrected while the stocktake is COUNTED. A different count restarts the row from the stock at that moment; see Stock that moves during a count.

Complete it

curl -X PATCH https://api.katanamrp.com/v1/stocktakes/7202001 \
  -H "Authorization: Bearer $KATANA_API_KEY" -H "Content-Type: application/json" \
  -d '{"status": "COMPLETED"}'

Completing posts the discrepancies as one stock adjustment, dated at completion: here −1 pcs of chain CH-2610 in A-01. Once status_update_in_progress is false, the stocktake is COMPLETED and stock_adjustment_id points to the adjustment. A stocktake with no discrepancies completes without one.

If stock moved while you were counting, completing can leave the stocktake COUNTED instead. See Stock that moves during a count.

Undo a completion

Set the stocktake back to COUNTED (or earlier) to remove its stock adjustment. A completed stocktake whose completion date falls in a closed inventory period can't be changed.