Skip to main content

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​

NameTypeDescriptionExample
idIDUnique Kojo internal identifier"clr8adymd000112nocbtsetzx"
identifierStringReceipt identifier. Draft and processing receipts carry the placeholder Draft until they complete"DLV-A0001"
stateWarehouseDeliveryReceiptStateTracks the state of the receiptCOMPLETE
modeWarehouseDeliveryReceiptModeWhether the receipt was received line by line or as a wholeITEMIZED
notesString?Receipt notes"Left at dock 3"
issuesJson?Issue types reported on the receipt["DAMAGED"]
purchaseOrderString?Purchase Order ID"clrrtqmy60007zay5y3kbb6x0"
releaseString?Release ID"clrrtqmy60007zay5y3kbb6x1"
notifiedContactsJsonEmails notified about the receipt["receiving@example.com"]
createdByString?ID of the user who created the receipt"clr6fkyru0002q3dwbwh2t6j8"
deletedBooleanIf true, the receipt has been deletedfalse
archivedAtDateTime?When a later receipt on the same Purchase Order archived this one"2024-01-10T21:22:26.053Z"
createdAtDateTimeCreation timestamp"2024-01-10T21:22:26.053Z"
updatedAtDateTimeLast updated timestamp"2024-01-10T21:22:26.053Z"
attachmentsFile[]Files attached to the receipt (read-only)[{ "id": "...", "name": "packing-slip.pdf", "url": "https://..." }]

WarehouseDeliveryReceiptItem​

NameTypeDescriptionExample
idIDUnique item identifier"clrrttruv000kzay5bj6gyf5u"
warehouseDeliveryReceiptIdIDWarehouse delivery receipt ID"clr8adymd000112nocbtsetzx"
itemString?Purchase Order item ID"clrrttruv000kzay5bj6gyfff"
typeWarehouseDeliveryReceiptItemTypeWhether the item is a commodity or a toolCOMMODITY
descriptionString?Item description"3/4 EMT"
notesString?Item notes"Two boxes crushed"
quantityFloat?Quantity expected10
unitsOfMeasureString?Unit of Measure"EA"
issuesJsonQuantities recorded on this receipt, keyed by condition{ "NO_ISSUES": 8, "DAMAGED": 2 }
quantityReceivedThisReceiptFloatQuantity received in good condition on this receipt8
skuString?SKU"EMT-075"
mpnString?Manufacturer part number"101543"
upcString?UPC"012345678905"
unitPriceFloat?Unit price1.25
scanResultScanResult?Packing slip scan match resultAI_MATCHED
scannedQuantityFloat?Quantity read from the packing slip10
createdAtDateTimeCreation timestamp"2024-01-10T21:22:26.053Z"
updatedAtDateTimeLast updated timestamp"2024-01-10T21:22:26.053Z"

File​

NameTypeDescriptionExample
idIDUnique file identifier"clr8adymd000112nocbtsetzx"
nameString?File name"packing-slip.pdf"
urlString?URL to download the file"https://storage.kojo.tech/files/..."
createdAtDateTimeFile upload timestamp"2024-01-10T21:22:26.053Z"
updatedAtDateTimeFile 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.

NameTypeDescription
NO_ISSUESNumberQuantity received in good condition
DAMAGEDNumberQuantity received damaged
MISSINGNumberQuantity missing
WRONG_ITEMNumberQuantity of wrong items received
BACKORDEREDNumberQuantity backordered

Enums​

WarehouseDeliveryReceiptState​

ValueDescription
DRAFTThe receipt is being filled in
PROCESSINGThe receipt is being submitted
COMPLETEThe receipt has been submitted and its materials received

WarehouseDeliveryReceiptMode​

ValueDescription
ITEMIZEDQuantities were recorded line by line
OVERALLThe delivery was received as a whole, without line quantities

WarehouseDeliveryReceiptItemType​

ValueDescription
COMMODITYA consumable material
TOOLA tool

ScanResult​

ValueDescription
AI_MATCHEDThe packing slip line was matched to this item
AI_UNMATCHEDThe 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​

NameDescriptionExample
idThe 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.

ValueDescription
NO_ISSUESItems received in good condition
MISSINGItems that are missing
DAMAGEDItems that are damaged
WRONG_ITEMWrong items received
BACKORDEREDItems that are backordered
ALLSpecial 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 issues include them. A receipt archived by a later receipt only matches NO_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​

NameDescriptionExample
warehouseDeliveryReceiptIdThe 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​

NameDescriptionExample
orderIdThe Kojo ID of the Purchase Order"clrrtqmy60007zay5y3kbb6x0"

Response​

A list of WarehouseDeliveryReceipt.

Example Query​

GET https://api.kojo.tech/orders/clrrtqmy60007zay5y3kbb6x0/warehouse-deliveries