Warehouse Deliveries
Warehouse Delivery Receipts track the arrival of materials at a warehouse. A receipt can be associated with a Purchase Order or not.
important
These endpoints cover Warehouse Deliveries only. Field deliveries are covered by Delivery Receipts (Field).
Schema​
WarehouseDeliveryReceipt​
| Name | Type | Description | Example |
|---|---|---|---|
| id | ID | Unique Kojo internal identifier | "clr8adymd000112nocbtsetzx" |
| identifier | String | Receipt identifier. Draft and processing receipts carry the placeholder Draft until they complete | "DLV-A0001" |
| state | WarehouseDeliveryReceiptState | Tracks the state of the receipt | COMPLETE |
| mode | WarehouseDeliveryReceiptMode | Whether the receipt was received line by line or as a whole | ITEMIZED |
| notes | String? | Receipt notes | "Left at dock 3" |
| issues | Json? | Issue types reported on the receipt | ["DAMAGED"] |
| purchaseOrder | String? | Purchase Order ID | "clrrtqmy60007zay5y3kbb6x0" |
| release | String? | Release ID | "clrrtqmy60007zay5y3kbb6x1" |
| notifiedContacts | Json | Emails notified about the receipt | ["receiving@example.com"] |
| createdBy | String? | ID of the user who created the receipt | "clr6fkyru0002q3dwbwh2t6j8" |
| deleted | Boolean | If true, the receipt has been deleted | false |
| archivedAt | DateTime? | When a later receipt on the same Purchase Order archived this one | "2024-01-10T21:22:26.053Z" |
| createdAt | DateTime | Creation timestamp | "2024-01-10T21:22:26.053Z" |
| updatedAt | DateTime | Last updated timestamp | "2024-01-10T21:22:26.053Z" |
| attachments | File[] | Files attached to the receipt (read-only) | [{ "id": "...", "name": "packing-slip.pdf", "url": "https://..." }] |
WarehouseDeliveryReceiptItem​
| Name | Type | Description | Example |
|---|---|---|---|
| id | ID | Unique item identifier | "clrrttruv000kzay5bj6gyf5u" |
| warehouseDeliveryReceiptId | ID | Warehouse delivery receipt ID | "clr8adymd000112nocbtsetzx" |
| item | String? | Purchase Order item ID | "clrrttruv000kzay5bj6gyfff" |
| type | WarehouseDeliveryReceiptItemType | Whether the item is a commodity or a tool | COMMODITY |
| description | String? | Item description | "3/4 EMT" |
| notes | String? | Item notes | "Two boxes crushed" |
| quantity | Float? | Quantity expected | 10 |
| unitsOfMeasure | String? | Unit of Measure | "EA" |
| issues | Json | Quantities recorded on this receipt, keyed by condition | { "NO_ISSUES": 8, "DAMAGED": 2 } |
| quantityReceivedThisReceipt | Float | Quantity received in good condition on this receipt | 8 |
| sku | String? | SKU | "EMT-075" |
| mpn | String? | Manufacturer part number | "101543" |
| upc | String? | UPC | "012345678905" |
| unitPrice | Float? | Unit price | 1.25 |
| scanResult | ScanResult? | Packing slip scan match result | AI_MATCHED |
| scannedQuantity | Float? | Quantity read from the packing slip | 10 |
| createdAt | DateTime | Creation timestamp | "2024-01-10T21:22:26.053Z" |
| updatedAt | DateTime | Last updated timestamp | "2024-01-10T21:22:26.053Z" |
File​
| Name | Type | Description | Example |
|---|---|---|---|
| id | ID | Unique file identifier | "clr8adymd000112nocbtsetzx" |
| name | String? | File name | "packing-slip.pdf" |
| url | String? | URL to download the file | "https://storage.kojo.tech/files/..." |
| createdAt | DateTime | File upload timestamp | "2024-01-10T21:22:26.053Z" |
| updatedAt | DateTime | File last updated timestamp | "2024-01-10T21:22:26.053Z" |
ReceiptItemIssues​
Quantities recorded on this receipt, keyed by condition. Once a later receipt on the same Purchase Order archives this one, only NO_ISSUES is returned.
| Name | Type | Description |
|---|---|---|
| NO_ISSUES | Number | Quantity received in good condition |
| DAMAGED | Number | Quantity received damaged |
| MISSING | Number | Quantity missing |
| WRONG_ITEM | Number | Quantity of wrong items received |
| BACKORDERED | Number | Quantity backordered |
Enums​
WarehouseDeliveryReceiptState​
| Value | Description |
|---|---|
| DRAFT | The receipt is being filled in |
| PROCESSING | The receipt is being submitted |
| COMPLETE | The receipt has been submitted and its materials received |
WarehouseDeliveryReceiptMode​
| Value | Description |
|---|---|
| ITEMIZED | Quantities were recorded line by line |
| OVERALL | The delivery was received as a whole, without line quantities |
WarehouseDeliveryReceiptItemType​
| Value | Description |
|---|---|
| COMMODITY | A consumable material |
| TOOL | A tool |
ScanResult​
| Value | Description |
|---|---|
| AI_MATCHED | The packing slip line was matched to this item |
| AI_UNMATCHED | The packing slip line could not be matched |
Queries​
GET /warehouse-deliveries/:id​
Fetches a single Warehouse Delivery Receipt by id. Receipts in any state can be fetched. Deleted receipts are not returned.
Parameters​
| Name | Description | Example |
|---|---|---|
| id | The Kojo ID of the warehouse delivery receipt to fetch | "clr8adymd000112nocbtsetzx" |
Response​
A single WarehouseDeliveryReceipt.
Example Query​
GET https://api.kojo.tech/warehouse-deliveries/clr8adymd000112nocbtsetzx
Example Response​
{
"id": "clr8adymd000112nocbtsetzx",
"identifier": "DLV-A0001",
"state": "COMPLETE",
"mode": "ITEMIZED",
"notes": null,
"issues": ["DAMAGED"],
"purchaseOrder": "clrrtqmy60007zay5y3kbb6x0",
"release": null,
"notifiedContacts": ["receiving@example.com"],
"createdBy": "clr6fkyru0002q3dwbwh2t6j8",
"deleted": false,
"archivedAt": null,
"createdAt": "2024-01-24T13:46:11.155Z",
"updatedAt": "2024-01-24T13:46:17.640Z",
"attachments": [
{
"id": "clr8adymd000112nocbtsetzy",
"name": "packing-slip.pdf",
"url": "https://storage.kojo.tech/files/packing-slip.pdf",
"createdAt": "2024-01-24T13:46:11.155Z",
"updatedAt": "2024-01-24T13:46:11.155Z"
}
]
}
GET /warehouse-deliveries​
Fetches multiple warehouse delivery receipts, according to filters.
Parameters​
Accepts all standard pagination parameters.
Allowed orderBy fields: id, identifier, notes, createdAt, updatedAt, archivedAt, state.
Allowed filter fields: id, identifier, notes, createdAt, updatedAt, archivedAt, state.
Only COMPLETE receipts are returned unless a state filter is sent (state, state_in, state_not or state_not_in), including when other filters are sent. Use a state filter to fetch DRAFT or PROCESSING receipts:
GET https://api.kojo.tech/warehouse-deliveries?filter[state_in]=DRAFT&filter[state_in]=PROCESSING
Accepts an includeDeleted boolean parameter which determines if deleted receipts will be returned (e.g. ?includeDeleted=true). By default, deleted receipts are not returned. Deleted receipts are returned with deleted set to true, whatever issueType_in is set to.
Deleting a receipt updates its updatedAt timestamp, so combining includeDeleted with an updatedAt filter surfaces receipts deleted since your last sync:
GET https://api.kojo.tech/warehouse-deliveries?includeDeleted=true&filter[updatedAt_gt]=2024-01-24T13:46:11.155Z
Issue Type Filter​
The issueType_in filter returns itemized receipts with an item that recorded every listed condition, and overall receipts (mode: OVERALL) whose issues include every listed condition.
| Value | Description |
|---|---|
NO_ISSUES | Items received in good condition |
MISSING | Items that are missing |
DAMAGED | Items that are damaged |
WRONG_ITEM | Wrong items received |
BACKORDERED | Items that are backordered |
ALL | Special value that turns off issue filtering |
Behavior:
- When omitted: Defaults to
NO_ISSUES, so only receipts received in good condition are returned - When
ALL: Returns receipts regardless of the conditions recorded - When specified: Returns itemized receipts with an item that recorded the listed conditions, and overall receipts whose
issuesinclude them. A receipt archived by a later receipt only matchesNO_ISSUES, because its other conditions no longer count
Examples:
# Get receipts with damaged items
GET https://api.kojo.tech/warehouse-deliveries?filter[issueType_in]=DAMAGED
# Get all completed receipts (bypass issue filtering)
GET https://api.kojo.tech/warehouse-deliveries?filter[issueType_in]=ALL
Response​
A list of WarehouseDeliveryReceipt.
Example Query​
GET https://api.kojo.tech/warehouse-deliveries?filter[createdAt_gt]=2024-01-01T00:00:00.000Z
Example Response​
[
{
"id": "clr8adymd000112nocbtsetzx",
"identifier": "DLV-A0001",
"state": "COMPLETE",
"mode": "ITEMIZED",
"notes": null,
"issues": [],
"purchaseOrder": "clrrtqmy60007zay5y3kbb6x0",
"release": null,
"notifiedContacts": [],
"createdBy": "clr6fkyru0002q3dwbwh2t6j8",
"deleted": false,
"archivedAt": null,
"createdAt": "2024-01-24T13:46:11.155Z",
"updatedAt": "2024-01-24T13:46:17.640Z",
"attachments": []
}
]
GET /warehouse-deliveries/:warehouseDeliveryReceiptId/items​
Fetches the items of a warehouse delivery receipt that have at least one quantity recorded. Items that only recorded damaged, missing, backordered or wrong-item quantities are included, except on a receipt archived by a later receipt, which only returns items with a NO_ISSUES quantity.
Parameters​
| Name | Description | Example |
|---|---|---|
| warehouseDeliveryReceiptId | The Kojo ID of the warehouse delivery receipt | "clr8adymd000112nocbtsetzx" |
Accepts all standard pagination parameters. Items are sorted by createdAt ascending by default.
Allowed orderBy fields: id, description, quantity, unitsOfMeasure, type, createdAt, updatedAt.
Allowed filter fields: id, description, quantity, unitsOfMeasure, type, createdAt, updatedAt.
Response​
A list of WarehouseDeliveryReceiptItem.
Example Query​
GET https://api.kojo.tech/warehouse-deliveries/clr8adymd000112nocbtsetzx/items
Example Response​
[
{
"id": "clrrttruv000kzay5bj6gyf5u",
"warehouseDeliveryReceiptId": "clr8adymd000112nocbtsetzx",
"item": "clrrttruv000kzay5bj6gyfff",
"type": "COMMODITY",
"description": "3/4 EMT",
"notes": "Two boxes crushed",
"quantity": 10,
"unitsOfMeasure": "EA",
"issues": { "NO_ISSUES": 8, "DAMAGED": 2 },
"quantityReceivedThisReceipt": 8,
"sku": null,
"mpn": null,
"upc": null,
"unitPrice": 1.25,
"scanResult": null,
"scannedQuantity": null,
"createdAt": "2024-01-24T13:46:11.155Z",
"updatedAt": "2024-01-24T13:46:11.155Z"
}
]
GET /orders/:orderId/warehouse-deliveries​
Fetches the warehouse delivery receipts of a Purchase Order. Accepts the same parameters as GET /warehouse-deliveries except includeDeleted, so only COMPLETE receipts are returned unless a state filter is sent. Receipts archived by a later receipt on the order are included.
issueType_in has no default on this route, so completed receipts are returned whatever their items recorded unless you send filter[issueType_in].
Parameters​
| Name | Description | Example |
|---|---|---|
| orderId | The Kojo ID of the Purchase Order | "clrrtqmy60007zay5y3kbb6x0" |
Response​
A list of WarehouseDeliveryReceipt.
Example Query​
GET https://api.kojo.tech/orders/clrrtqmy60007zay5y3kbb6x0/warehouse-deliveries