Create an Item Receipt from a Purchase Order: /purchase-orders/{id}/item-receipts
Purpose
Create a new item receipt against a specific purchase order. An item receipt records the physical receipt of goods from a supplier, capturing which line items were received, in what quantities, and any associated tracking information. This endpoint accepts the receipt details including status, date, tracking number, a note, and an array of receipt lines referencing the purchase order line items by their UUIDs along with the quantities received. Upon successful creation, the system returns the complete item receipt object with generated identifiers and audit metadata nested under the purchase order context.
Use Case
This endpoint is used to record the receipt of goods against a purchase order. It is commonly used in warehouse and inventory management workflows when shipments arrive from suppliers and need to be logged against the corresponding purchase order. Warehouse staff can record partial or full receipts by specifying the quantity received for each line item, enabling accurate tracking of outstanding deliveries. The tracking number field supports logistics workflows where shipment tracking references need to be associated with the receipt for traceability. The note field allows warehouse teams to capture observations about the condition of goods, discrepancies, or special handling instructions at the time of receipt. This endpoint also supports three-way matching workflows where the item receipt is compared against the purchase order and the supplier invoice to verify that the correct goods were received before authorizing payment.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| purchase_order_id | String | The unique ID of the purchase order (e.g., PO-RTO8M6-0006) |
Query Parameters
No query parameters required.
Request Body
{
"item-receipt": {
"receipt_status": "PENDING",
"date": "2026-03-08",
"id": "IR-65546809",
"tracking_number": "19882002",
"note": "Item is packed",
"receipts": [
{
"line_uuid": "99a2865a-75aa-4371-aa77-e9b40589d774",
"receipt_quantity": "2.00"
}
]
}
}| Attribute | Type | Description |
|---|---|---|
| receipt_status | String | Status of the item receipt (e.g., PENDING) |
| date | String (ISO 8601) | Date of the item receipt |
| id | String | Human-readable item receipt ID |
| tracking_number | String | Shipment tracking number (optional) |
| note | String | Note or description for the receipt (optional) |
| receipts | Array | List of receipt line items |
| receipts[].line_uuid | String (UUID) | UUID of the purchase order line item being received |
| receipts[].receipt_quantity | String | Quantity received for the line item |
Response
Returns the complete item receipt object nested under the purchaseOrder wrapper. The response includes the itemReceipts array where each receipt contains the receipt status, date, human-readable ID, associated purchase order ID, tracking number, note, and a receipts array with the line-level details. Each receipt line includes the line UUID, item ID, unit of measure, warehouse, quantity received, and remaining quantity left to receive. Audit fields (createdBy, createdOn, lastUpdatedBy, lastUpdatedOn) and a uuid and version number are also included. The pagination object provides metadata for navigating through results.
Response Body
{
"purchaseOrder": {
"itemReceipts": [
{
"receiptStatus": "RECEIPT_STATUS",
"date": "RECEIPT_DATE",
"id": "ITEM_RECEIPT_ID",
"purchaseOrderId": "PURCHASE_ORDER_ID",
"trackingNumber": "TRACKING_NUMBER",
"note": "RECEIPT_NOTE",
"receipts": [
{
"lineUuid": "LINE_UUID",
"itemId": "ITEM_ID",
"uom": "UNIT_OF_MEASURE",
"warehouse": "WAREHOUSE",
"receiptQuantity": "RECEIPT_QUANTITY",
"receiptLeft": "RECEIPT_LEFT"
}
],
"createdBy": "CREATED_BY_USER",
"createdOn": "CREATED_ON_DATETIME",
"lastUpdatedBy": "LAST_UPDATED_BY_USER",
"lastUpdatedOn": "LAST_UPDATED_ON_DATETIME",
"uuid": "ITEM_RECEIPT_UUID",
"version": "ITEM_RECEIPT_VERSION"
}
],
"pagination": {
"records": "TOTAL_RECORD_COUNT",
"limit": "PAGE_LIMIT",
"offset": "PAGE_OFFSET",
"previousPage": "PREVIOUS_PAGE_URL",
"nextPage": "NEXT_PAGE_URL"
}
}
}| Attribute | Type | Description |
|---|---|---|
| itemReceipts | Array | List of item receipts for the purchase order |
| receiptStatus | String | Status of the item receipt (e.g., PENDING, RECEIVED) |
| date | String (ISO 8601) | Date of the item receipt |
| id | String | Human-readable item receipt ID |
| purchaseOrderId | String | Associated purchase order ID |
| trackingNumber | String | Shipment tracking number |
| note | String | Note or description for the receipt |
| receipts | Array | List of receipt line items |
| receipts[].lineUuid | String (UUID) | UUID of the purchase order line item |
| receipts[].itemId | String | Human-readable item identifier |
| receipts[].uom | String | Unit of measure |
| receipts[].warehouse | String | Warehouse identifier |
| receipts[].receiptQuantity | String | Quantity received |
| receipts[].receiptLeft | String | Remaining quantity to receive |
| createdBy | String | Username of the receipt creator |
| createdOn | String (ISO 8601) | Timestamp when the receipt was created |
| lastUpdatedBy | String | Username of the last editor |
| lastUpdatedOn | String (ISO 8601) | Timestamp of the last update |
| uuid | String (UUID) | UUID of the item receipt |
| version | String | Version number of the item receipt |
| pagination.records | Integer | Total number of matching records |
| pagination.limit | Integer | Page size limit |
| pagination.offset | Integer | Current page offset |
| pagination.previousPage | String | URL for the previous page of results |
| pagination.nextPage | String | URL for the next page of results |