# Materials and stock

**Materials & stock** is what the company keeps on hand: sealer in the tank, crack filler and paint in the yard, what is riding on each truck. TruTec ties it to the rest of the work, so it knows what the jobs on the schedule still need from stock, and using stock on a job puts the cost on that job.

A workspace needs TruTec Bid or Build with Materials & stock on (Settings › Workspace); others get `403`. Every write runs as the key's creator with the same rules as the stock board in the app. A workspace that keeps its stock in NetSuite is read-only here (`409` on writes).

## What is on hand

`GET /v1/stock/materials` returns every stocked material, a page at a time.

| Filter | What it does |
|---|---|
| `q` | Words in the name, SKU, group or supplier |
| `state` | `low` (at or below its reorder point), `out`, `short` (short for a scheduled job) or `on_order` |
| `place_id` | Only what is at one place, such as a truck |

Each material carries `on_hand`, where it sits (`places`), `held_for_scheduled_jobs` (what scheduled jobs still need, from their estimates), `free`, `short_for_scheduled_jobs`, `on_order`, and `to_buy`: what TruTec suggests ordering and why. `average_cost` and `value` are present when the key's creator may see prices. The answer's `summary` has the totals for the whole list.

```bash
curl "https://trutec.ai/api/v1/stock/materials?q=sealer" \
  -H "X-API-Key: $TRUTEC_API_KEY"
```

`GET /v1/stock/places` lists the yard, the shop, each tank and each truck. Use a place's `id` as `place_id` in the calls below.

## Stock moves

All four take `quantity` in the material's own unit; send `in_packs: true` when you mean packs (10 pails of a material counted by the gallon).

| Call | What it does |
|---|---|
| `POST /v1/stock/materials/{material_id}/receive` | A delivery arrived that is not on a purchase order. `unit_cost` re-averages the material's cost |
| `POST /v1/stock/materials/{material_id}/move` | Move it between places: `from_place_id`, `to_place_id` |
| `POST /v1/stock/materials/{material_id}/use` | Use it on a job: `job_id` puts one material cost on that job at average cost. Leave `job_id` out to take it out with no job |
| `POST /v1/stock/materials/{material_id}/count` | Say what is really at a place: `place_id`, `counted` (a tank takes `"60%"`) |

Each answers with a plain `message` ("Moved 20 GAL Asphalt sealer: Yard → Truck 4."), the `job_id` it was charged to when there is one, and the material as it stands now.

```bash
curl -X POST "https://trutec.ai/api/v1/stock/materials/31/move" \
  -H "X-API-Key: $TRUTEC_API_KEY" -H "Content-Type: application/json" \
  -d '{"quantity": 20, "from_place_id": 1, "to_place_id": 4}'
```

Putting stock on a job's costs needs the key's creator to see prices and to be able to open that job.

## Purchase orders

`GET /v1/stock/purchase-orders` lists supplier purchase orders (`status=open` for drafts and orders still coming) and `GET /v1/stock/purchase-orders/{order_id}` returns one with its lines. These are orders for materials bought from a supplier; a purchase order given to a subcontractor is a different record.

`POST /v1/stock/purchase-orders` puts stocked materials on a supplier's **draft** order. The supplier's open draft is reused, prices come from that supplier's price list with their volume break, and nothing is sent: a person reviews the email and PDF and sends it in TruTec under Materials & stock › Orders.

```bash
curl -X POST "https://trutec.ai/api/v1/stock/purchase-orders" \
  -H "X-API-Key: $TRUTEC_API_KEY" -H "Content-Type: application/json" \
  -d '{"supplier_name": "SealMaster", "lines": [{"material_id": 35, "quantity": 10, "in_packs": true}]}'
```

## From ChatGPT or Claude

The connector has a tool for each call: `get_stock_materials`, `get_stock_places`, `receive_stock_material`, `move_stock_material`, `use_stock_material`, `count_stock_material`, `get_stock_purchase_orders` and `create_stock_purchase_order`. So "how much sealer do we have", "move 20 gallons to truck 4" and "order 10 pails of crack filler from SealMaster" each map to one tool; the order is always a draft for a person to send.
