> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receiving and put-away

> Inbound shipments, receipts, put-away tasks, and cycle counts — how goods enter the building without corrupting inventory.

# Receiving and put-away

Inventory accuracy is won or lost at the door. The inbound flow has three separated stages —
**shipment** (it's coming), **receipt** (it's here, counted), **put-away** (it's on a shelf,
findable) — and the separation exists because each stage can disagree with the last.

## 1 — Track the inbound shipment

```bash theme={null}
curl -X POST https://api.stateset.com/api/v1/inbound-shipments \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "purchase_order_id": "po_301", "carrier": "maersk", "expected_arrival": "2026-08-04" }'
```

Status moves with `POST /api/v1/inbound-shipments/{id}/in-transit` and `/{id}/arrived`. The shipment
is the *expectation* — what the supplier says is on the truck.

## 2 — Receive against a receipt

```bash theme={null}
curl -X POST https://api.stateset.com/api/v1/receipts \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "inbound_shipment_id": "ib_77" }'

curl -X POST https://api.stateset.com/api/v1/receipts/{id}/start   -H "Authorization: Bearer $STATESET_API_KEY"

curl -X POST https://api.stateset.com/api/v1/receipts/{id}/receive \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "sku": "SHOE-RED-10", "quantity": 480, "condition": "good" }'

curl -X POST https://api.stateset.com/api/v1/receipts/{id}/complete -H "Authorization: Bearer $STATESET_API_KEY"
```

The receipt records what was **actually in the boxes** — 480, not the 500 the PO ordered. Item by
item, condition included. Completing the receipt is what updates on-hand inventory and feeds the
[three-way match](/guides/commerce/procure-to-pay#4--three-way-match) on the supplier's bill.

<Warning>
  Never "receive to the PO" — entering ordered quantities instead of counting. It feels faster and it
  poisons everything downstream: on-hand shows units that never arrived, picks come up
  [short](/guides/commerce/fulfillment#2--pick), and the three-way match approves a bill for goods you
  don't have. The count at the dock is the only count that's cheap.
</Warning>

Lot-tracked or serialized items get their lot/serial recorded at this step — see
[traceability](/guides/commerce/traceability). Damaged goods take `"condition": "damaged"` and go to
[quarantine or back to the vendor](/guides/commerce/returns-and-rtv#return-to-vendor), not onto a
sellable shelf.

## 3 — Put away

```bash theme={null}
curl -X POST https://api.stateset.com/api/v1/put-aways \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "receipt_id": "rcp_12", "to_location_id": 4407 }'

curl -X POST https://api.stateset.com/api/v1/put-aways/{id}/complete -H "Authorization: Bearer $STATESET_API_KEY"
```

Received-but-not-put-away stock is real but **unfindable** — it exists in totals and not on any
shelf a picker visits. The put-away task closes that gap and stamps the location
(`GET /api/v1/warehouse-locations/{id}/inventory` shows what's where). Watch the age of open
put-aways; a dock full of completed receipts is inventory you own and cannot sell.

## When the count is wrong

Two tools, different jobs:

```bash theme={null}
# Scheduled verification: count a location, reconcile
curl -X POST https://api.stateset.com/api/v1/cycle-counts \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "location_id": 4407 }'
# then /{id}/start, /{id}/counts with what you found, /{id}/complete
```

```bash theme={null}
# Known discrepancy right now: adjust, with a reason
curl -X POST https://api.stateset.com/api/v1/warehouse-inventory/adjust \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "location_id": 4407, "sku": "SHOE-RED-10", "delta": -2, "reason": "damaged in racking" }'
```

<Tip>
  Cycle counts are the habit that replaces the annual full-count nightmare: a few locations a day,
  biased toward fast movers and recent discrepancies. `adjust` is for the moment you're holding the
  broken item — always with a reason, because a pattern of "shrinkage" adjustments at one location is
  a finding, not noise.
</Tip>

## Related

* [Procure to pay](/guides/commerce/procure-to-pay) — the PO this shipment fulfils
* [Fulfillment](/guides/commerce/fulfillment) — the outbound mirror
* [Traceability](/guides/commerce/traceability) — lots, serials, quarantine