Delivery Receipts (Field)

Delivery Receipts track the arrival of materials at Job sites. Deliveries can be associated or not with a Purchase Order.

important

This endpoint supports Field Deliveries only. It does not cover Warehouse Deliveries.

Schema

DeliveryReceipt

Name	Type	Description	Example
id	ID	unique item identifier	"clrrttruv000kzay5bj6gyf5u"
deliveryReceiptId	ID	delivery receipt unique identifier	"clrrttruv000kzay5bj6gyf5u"
description	String	item description	"3/4 EMT"
notes	String?	delivery receipt item notes	"No issues"
quantity	float	overall quantity	5
quantityReceivedThisReceipt	float	quantity received in this receipt	3
unitsOfMeasure	String	Unit of Measure	"EA"
issues	Json	Issue counts for this item, keyed by issue type	{ "MISSING": 1, "DAMAGED": 0 }
deleted	Boolean?	If true the delivery receipt has been deleted	false
createdAt	DateTime	Creation timestamp	"2024-01-10T21:22:26.053Z"
updatedAt	DateTime	Last updated timestamp	"2024-01-10T21:22:26.053Z"
integrationMessage	string?	A message about the status of the integration's sync	"PO number already exists"
integrationState	IntegrationState?	The status of the Delivery sync to another integrated system	NOT_LINKED
attachments	File[]	List of files attached to the delivery receipt (read-only)	[{ "id": "...", "name": "packing-slip.pdf", "url": "https://..." }]

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

The issues field is a Json object whose keys are issue types and whose values are counts.

Name	Type	Description
MISSING	int	Amount of items missing
DAMAGED	int	Amount of damaged items
NO_ISSUES	int	Amount of items without issues
WRONG_ITEM	int	Amount of wrong items received
BACKORDERED	int	Amount of items backordered

Enums

DeliveryReceiptState

Value	Description
SUBMITTED	When the receipt has been submitted
DRAFT	When the receipt submition is pending

IntegrationState

Value	Description
NOT_LINKED	All deliveries start in this un-linked state
LINKING	Linking to the other system is in progress
LINKED	The delivery was successfully linked to the other system
OUT_OF_SYNC	A change was made after linking; the record must be re-synced to the other system
LINKING_CHANGE_ORDER	A related change order is currently being synced to the other system
COS_NOT_LINKED	A related change order has not yet been linked to the other system
COS_WITH_ERRORS	An error occurred while syncing a related change order to the other system
ERROR	An error occurred while trying to sync the delivery to the other system. When this state is used, it's helpful to set an integrationMessage explaining the problem to the user.

Queries

deliveryReceipt

Fetches a single Delivery Receipt by id or identifier.

Parameters

Name	Description	Example
id	The Kojo ID of the delivery receipt to fetch	"ckmnpybisiy5x08abky4g2d1f"
identifier	The identifier of the delivery receipt	"DLV-A0001"

Response

A single Delivery Receipt.

Example Query

query {
  deliveryReceipt(id: "ckmnpybisiy5x08abky4g2d1f") {
    id
    identifier
    notes
    state
    createdAt
    updatedAt
    archivedAt
    attachments {
      id
      name
      url
    }
  }
}

Example Response

{
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "identifier": "DLV-A0001",
  "notes": null,
  "createdAt": "2024-01-10T21:22:26.053Z",
  "archivedAt": null,
  "updatedAt": "2024-01-10T21:22:34.850Z",
  "state": "SUBMITTED",
  "attachments": [
    {
      "id": "clr8adymd000112nocbtsetzx",
      "name": "packing-slip.pdf",
      "url": "https://storage.kojo.tech/files/packing-slip.pdf"
    }
  ]
}

deliveryReceipts

Fetches multiple 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.

Accepts an includeDeleted boolean parameter which determines if deleted delivery receipts will be returned (e.g. includeDeleted: true). By default, deleted delivery receipts are not returned. Deleted receipts are returned with deleted set to true.

Deleting a delivery receipt updates its updatedAt timestamp, so combining includeDeleted with an updatedAt filter surfaces receipts deleted since your last sync.

Response

A list of Delivery Receipts.

Example Query

query {
  deliveryReceipts(
    orderBy: createdAt,
    direction: DESC
  ) {
    id
    identifier
    createdAt
  }
}

Example Response

[
  {
    "id": "clr8adymd000112nocbtsetzx",
    "identifier": "DLV-A0001",
    "createdAt": "2024-01-10T21:22:26.053Z",
  }
]

orderDeliveryReceipts

Fetches all delivery receipts associated with a Purchase Order.

Parameters

Name	Type	Description	Example
orderId	ID	Purchase Order unique ID	"ckmnpybisiy5x08abky4g2d1f"

Accepts the same filtering and ordering parameters from deliveryReceipts query.

Example Query

query {
  oderDeliveryReceipts(orderId: "ckmnpybisiy5x08abky4g2d1f"){
    id
    identifier
    createdAt
  }
}

Example Response

[
  {
    "id": "clr8adymd000112nocbtsetzx",
    "identifier": "DLV-A0001",
    "createdAt": "2024-01-10T21:22:26.053Z",
  }
]

deliveryReceiptItems

Fetches all delivery receipt Items associated with a delivery.

Parameters

Name	Type	Description	Example
deliveryReceiptId	ID	Delivery Receipt unique ID	"ckmnpybisiy5x08abky4g2d1f"

Example Query

query {
  deliveryReceiptItems(deliveryReceiptId: "ckmnpybisiy5x08abky4g2d1f"){
    id
    deliveryReceiptId
    description
    quantity
    issues
    notes
    quantityReceivedThisReceipt
    unitsOfMeasure
    createdAt
    updatedAt
  }
}

Example Response

[
  {
    "id": "clrrttruw000mzay5lpuy36bu",
    "deliveryReceiptId": "clrrttruv000kzay5bj6gyf5u",
    "createdAt": "2024-01-24T13:34:13.832Z",
    "updatedAt": "2024-01-24T13:34:23.446Z",
    "description": "3/4 EMT",
    "notes": "test note",
    "quantity": 1,
    "quantityReceivedThisReceipt": 1,
    "unitsOfMeasure": "EA",
    "issues": {
        "NO_ISSUES": 1
    }
  }
]

Mutations

updateDeliveryReceiptIntegrationState

Updates the Delivery Receipt integration status.

Parameters

Name	Type	Description	Example
id	ID	Unique identifier for orders	"ckmnpybisiy5x08abky4g2d1f"
integrationMessage	string?	A message about the status of the integration's sync. Required if the status is being set to ERROR	"Delivery Receipt already exists"
integrationState	IntegrationState	The new status of the order's sync to your integrated system	NOT_LINKED

Example Query

mutation {
  updateDeliveryReceiptIntegrationState(
    id: "ckmnpybisiy5x08abky4g2d1f",
    integrationState: "LINKED",
    integrationMessage: ""
  ) {
    id
    integrationMessage
    integrationState
  }
}

Example Response

{
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "integrationState": "LINKED",
  "integrationMessage": ""
}