--- title: "Receives purchase-order lines into stock (the app's receiving panel)." method: POST path: "/api/v1/purchase-orders/{id}/receive" tags: ["PurchaseOrders"] --- # Receives purchase-order lines into stock (the app's receiving panel). `POST /api/v1/purchase-orders/{id}/receive` ## Request - Base URL: `https://app.flexonthejob.com` - URL: `https://app.flexonthejob.com/api/v1/purchase-orders/{id}/receive` - Auth: HTTP bearer Requires `ManagePurchaseOrders` and an `Idempotency-Key` header. Body: `{ "lines": [ { "lineId": 1207, "quantity": 4 }, { "lineId": 1208, "quantity": 1, "locationId": 11 } ] }`. Same code path and rules as receiving in the app: only an order whose `status` is `Delivered` or `PartialReceived` can be received (409 otherwise, e.g. for a `Cancelled`, `Ordered` or fully `Received` order); every line is checked before anything is written (one bad line and nothing is received); a quantity above the line's `quantityRemaining` is refused (over-receipt, also when a concurrent receipt of the same line got there first); `locationId` defaults to the order's `receivingLocationId`. An item line creates one stock item per unit at that location, with the template's properties, barcodes and category, a `Cost` property from the line's `unitPrice`, and `Shipping Cost` / `Total Cost` properties when the line is on a shipment with a shipping cost; a bundle line creates one bundle per unit with its items. The order `status` is then recomputed from its shipments: it becomes `Received` when every unit is received and every shipment is delivered, otherwise `PartialReceived`. The receipt is attributed to the key's creator. Returns the order as `GET /api/v1/purchase-orders/{id}` does. ## Path parameters - `id` integer, required ## Request body - ReceivePurchaseOrderApiRequest: Body of `POST /api/v1/purchase-orders/{id}/receive`. Example: `{ "lines": [ { "lineId": 1207, "quantity": 4 }, { "lineId": 1208, "quantity": 1, "locationId": 11 } ] }`. - `lines` ReceivePurchaseOrderLineApiRequest[], required: Lines to receive (1–200 entries). All are validated before anything is written; the first problem is reported and nothing is received. - `lineId` integer: The line's `id` from `GET /api/v1/purchase-orders/{id}`. Example: `1207`. - `quantity` integer: Whole units received now, 1 to the line's `quantityRemaining` (a line repeated in the same request counts against the same remaining quantity). Example: `4`. - `locationId` integer, nullable: Location the stock is created at (see `/api/v1/locations`); must be a location of this organization that is not deleted. Omit to use the order's `receivingLocationId`. Example: `11`. ## Response `200` The purchase order after the receipt. - PurchaseOrderDetailDto: One purchase order with its lines, as returned by `GET /api/v1/purchase-orders/{id}` and by `POST /api/v1/purchase-orders/{id}/receive`. - `id` integer: Numeric id used in `/api/v1/purchase-orders/{id}`. Unique within this organization. Example: `412`. - `syncId` string, uuid: Stable cross-device identifier (GUID) — also the pagination cursor value. Example: `3c9d1a2b-7e4f-4b6a-8c1d-5e6f7a8b9c0d`. - `orderNumber` string: The organization's purchase-order number. Example: `PO-ACME-20260915-01`. - `externalOrderNumber` string, nullable: The vendor's own order or confirmation number; null when not recorded. Example: `SO-88213`. - `status` string: Order status name, derived by the app from the order's shipments and received quantities. One of `Draft` (no shipment yet), `Ordered`, `Shipped`, `PartialShipped`, `Delivered` (at the receiving location, nothing received yet), `PartialReceived`, `Received` (every unit received and every shipment delivered), `Cancelled`. - `vendorId` integer, nullable: Id of the vendor record; null for a one-off vendor typed on the order. - `vendorName` string, nullable: Vendor name (the vendor record's name, else the one-off name on the order). Example: `Acme Supply`. Null when neither is set. - `orderDate` string, date-time: Order date as entered in the app: the organization's local calendar date, `yyyy-MM-ddT00:00:00` with no UTC offset (the `date-time` format here is a local date, not an RFC 3339 instant; do not convert it between time zones). Example: `2026-09-15T00:00:00`. - `expectedDeliveryDate` string, date-time, nullable: Expected delivery date as entered in the app, same local calendar-date format as `orderDate` (no UTC offset). Example: `2026-09-22T00:00:00`. Null when unknown. - `receivedDate` string, date-time, nullable: When the order became fully `Received`, ISO-8601 UTC; null until then. - `totalCost` number, double, nullable: Order total in `currency` as recorded on the order; null when not calculated. Example: `1249.50`. - `currency` string: ISO-4217 currency code of the prices on the order. Example: `USD`. - `receivingLocationId` integer: Id of the location stock is received at by default (see `/api/v1/locations`). Example: `10`. - `receivingLocationName` string, nullable: Name of `receivingLocationId`. Example: `Main Warehouse`. - `lineCount` integer: Number of lines on the order. Example: `3`. - `quantityOrdered` integer: Units ordered across all lines. Example: `40`. - `quantityReceived` integer: Units received across all lines. Example: `25`. - `createdAt` string, date-time: Creation time, ISO-8601 UTC. Example: `2026-09-15T14:05:00Z`. - `updatedAt` string, date-time, nullable: Last modification time (including a receipt), ISO-8601 UTC; null when never modified since creation. - `notes` string, nullable: Free-text notes on the order. Example: `Deliver to dock 3.` Null when none. - `lines` PurchaseOrderLineDto[]: The order lines, in the order they were added. - `id` integer: Line id — the `lineId` to pass to `POST /api/v1/purchase-orders/{id}/receive`. Example: `1207`. - `itemId` integer, nullable: Item (template) id as used by `/api/v1/items/{id}`; null for a bundle line. - `bundleTemplateId` integer, nullable: Bundle template id for a bundle (kit) line; null for an item line. - `name` string, nullable: What is ordered: the item or bundle name at read time, else the line description. Example: `Copper 12/2 Romex`. - `description` string, nullable: Line description as entered on the order. Example: `Copper 12/2 Romex, 250 ft`. - `vendorPartNumber` string, nullable: The vendor's part number; null when not recorded. Example: `RMX-122-250`. - `quantityOrdered` integer: Units ordered. Example: `10`. - `quantityShipped` integer: Units the vendor has shipped, as recorded on the order. Example: `10`. - `quantityReceived` integer: Units received into stock so far. Example: `6`. - `quantityRemaining` integer: Units still to receive (`quantityOrdered` minus `quantityReceived`) — the most `receive` accepts for this line. Example: `4`. - `unitPrice` number, double, nullable: Unit price in the order's `currency`; becomes the `Cost` property of each received item. Null when not priced. Example: `89.99`. - `lineTotal` number, double, nullable: Line total in the order's `currency`; null when not calculated. Example: `899.90`. - `shipmentId` integer, nullable: Id of the shipment the line travels on; null when not assigned to a shipment. Received items on a shipment with a shipping cost get `Shipping Cost` and `Total Cost` properties. ## Other responses - `400`: Missing `Idempotency-Key`, or a malformed body (no lines, `quantity` below 1; fields listed in `errors`). - `401`: Unauthorized - `403`: Forbidden - `404`: No such purchase order in this organization (or it is deleted). - `409`: The order is not `Delivered` or `PartialReceived` (detail: `Purchase order is Cancelled; only Delivered or PartialReceived orders can be received`), or the key's creator is unknown on this server. Nothing was received. - `422`: A line cannot be received: `Item not found in purchase order` (unknown `lineId`), `Cannot receive more than N remaining units` (over-receipt), or `Invalid destination location`; the offending field (e.g. `lines[0].quantity`) is listed in `errors`. Nothing was received. - `429`: Too Many Requests --- [API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)