Orders

Orders, also known as purchase orders, track the costs and details surrounding a request for materials, equipment, or other job costs.

Schema

Order

Name	Type	Description	Example
id	ID	Unique identifier for orders	"ckmnpybisiy5x08abky4g2d1f"
createdAt	DateTime	When this order was created	"2021-03-24 17:26:46.983Z"
deliveryInstructions	string?	Additional instructions for how to deliver the items	"Gate code is 1234"
discount	float?	The dollar amount of discounts to subtract from the order total	125.60
fieldContactName	string?	Name of the field contact receiving the order	"John Doe"
fieldContactPhone	string?	Phone number of the field contact receiving the order	"8001854367"
flagged	boolean	Tracks whether the order has been flagged with an issue	true
flaggedAt	DateTime?	The date/time this order was flagged	"2021-03-24 17:26:46.983Z"
flagMessage	string?	User's description of the flagged issue with this order	"Missing items"
glCode	GLCode?	The default GL code to use for items in this order (includes only the id and code fields)	See GL Code docs
integrationLastSync	DateTime?	(Read-only) Last time the order's integrationState was updated to LINKED	"2021-03-24 17:26:46.983Z"
integrationMessage	string?	A message about the status of the integration's sync	"PO number already exists"
integrationState	IntegrationState?	The status of the order's sync to another integrated system	NOT_LINKED
mode	OrderMode	The mode the order originated in	"REQUEST_FOR_QUOTE"
needByDateDay	DateTime?	The date the order is needed by	"2021-03-24 17:26:46.983Z"
needByWindow	NeedByWindow	Window the order should be delivered by	ASAP
notes	string?	Additional handwritten details attached to this order	"Call Mike when this arrives"
purchaseOrderNumber	string?	User-defined value to identify this order	"1234"
shippingCost	float?	The dollar amount of shipping costs to add to the order total	1200.30
state	OrderState	The current state of the order	BID_CANCELLED
taxCode	TaxCode?	The default tax code to use for items in this order (includes only the id, code, taxPercent fields)	See Tax Code docs
attachments	OrderAttachment[]	The attachments associated with the order	See OrderAttachment[]
taxExempt	boolean?	Indicates that the order is exempt from any and all tax rates entered on line items	false
type	OrderType	Type of order, either STANDARD or HOLD_FOR_RELEASE	HOLD_FOR_RELEASE
updatedAt	DateTime	When this order was last updated	"2021-03-24 17:26:46.983Z"
createdById	ID	The user id who created the order	"ckmnpybisiy5x08abky4g2d1f"
updatedById	ID	The user id who last updated the order	"ckmnpybisiy5x08abky4g2d1f"
receivedState	ReceivedState	The Deliveries state	"FULLY_RECEIVED"
customColumnValue	string?	Value associated with the custom column	"438076873"

Enums

IntegrationState

Value	Description
NOT_LINKED	All orders start in this un-linked state
LINKING	Linking to the other system is in progress
LINKED	The order was successfully linked to the other system
OUT_OF_SYNC	If a change is made to an order in Kojo after it is LINKED, Kojo will update the order to this status
ERROR	An error occurred while trying to sync the order to the other system. When this state is used, it's helpful to set an integrationMessage explaining the problem to the user.

ReceivedState

Value	Description
NO_DELIVERIES	No deliveries submitted yet.
PARTIALLY_RECEIVED	Deliveries were submitted but there still items to be received
FULLY_RECEIVED	All items have been received

NeedByWindow

Value	Description
ASAP	As soon as possible
AMEarly	Early morning
AM	Morning
PM	Afternoon
PMLate	Late Afternoon
UNSPECIFIED	Unspecified

OrderMode

Value	Description
ISSUE_PO	Order is issued to a single vendor
PRE_ACKNOWLEDGED	Order is pre-acknowledged by the vendor outside Kojo
REQUEST_FOR_QUOTE	Order is issued to multiple vendors for quotes

OrderState

Value	Description
DRAFT	All orders start in draft
BID_ACTIVE	In bid state
BID_CANCELLED	If an RFQ has been cancelled
FINALIZING	Order has been sent but not acknowledged
ACTIVE	Order has been acknowledged
CANCELLED	Order has been cancelled
COMPLETE	Order has been completed

OrderAttachment

Name	Type	Description	Example
id	ID	Unique identifier for the attachment	"ckmnpybisiy5x08abky4g2d1f"
createdAt	DateTime	The date and time when the attachment was created	"2024-09-03T12:00:00Z"
updatedAt	DateTime	The date and time when the attachment was last updated	"2024-09-03T12:00:00Z"
identifier	string?	Optional unique identifier for the attachment	"invoice-1234"
file	File	The file associated with the attachment. May include details such as URL or metadata.

File

Name	Type	Description	Example
id	ID	Unique identifier for the file	"ckmnpybisiy5x08abky4g2d1f"
name	string?	Name of the file	"document.pdf"
createdAt	DateTime	When this file was created	"2024-09-03T12:00:00Z"
updatedAt	DateTime	When this file was last updated	"2024-09-03T12:00:00Z"
url	string?	URL where the file can be accessed	"https://example.com/file1.pdf"

OrderType

Value	Description
HOLD_FOR_RELEASE	A hold for release (HFR) order, also referred to as a buyout
STANDARD	A standard order

OrderInput

Name	Type	Description	Example
fieldContactName	string?	The name of the field person who will receive this order	"John Doe"
fieldContactPhone	string?	A valid phone number for the field person who will receive this order	"800-185-4367"
purchaseOrderNumber	string	A unique string to represent this purchase order	"PO-1234"
needByDateDay	DateTime?	When this order is needed by	"2021-03-24 17:26:46.983Z"
needByWindow	NeedByWindow	Window the order should be delivered by	AMEarly
deliveryInstructions	string?	Additional instructions for how to deliver the items	"Gate code is 1234"
distributorContactName	string?	The name of the distributor this order will be sent to	"Jane Distributor"
distributorContactEmail	string	A valid email address for the distributor associated with this purchase order	"jane@distributor.com"
distributorContactPhone	string?	A valid phone number for the distributor associated with this purchase order	"800-185-4367"
distributorContactCompany	string	The name of the company for the distributor associated with this purchase order	"Electric Supply Co."
isVisibileToField	boolean?	Whether or not field users of Kojo can see this purchase order	true
notes	string?	Additional handwritten details attached to this order	"Call Mike when this arrives"
discount	float?	The dollar amount of discounts to subtract from the order total	125.60
shippingCost	float?	The dollar amount of shipping costs to add to the order total	1200.30
taxExempt	boolean?	Indicates that the order is exempt from any and all tax rates entered on line items	true
title	string?	The title for this purchase order in KOJO	"Extra Conduit Order"
deliveryLocationId	ID?	The id of delivery location for this order	"ckmnpybisiy5x08abky4g2d1f"
jobId	ID?	The id of the job for this order	"ckmnpybisiy5x08abky4g2d1f"
vendorId	ID?	The id of the vendor for this order	"ckmnpybisiy5x08abky4g2d1f"
createdById	ID?	The user id of the procurement representative for this order	"ckmnpybisiy5x08abky4g2d1f"
requisitionIds	ID[]?	The IDs of any Requisitions that this Order is sourced from	["ckmnpybisiy5x08abky4g2d1f"]
state	OrderState	The state of the order	ACTIVE

ItemInput

Name	Type	Description	Example
lineNumber	int	Number representing the index of the line item within it's order	3
quantity	float?	Quantity of this item	100.0
unitsOfMeasure	string?	Unit of measurement for this item	"IN"
description	string?	Description of the item	"3/4 in EMT"
manufacturer	string?	Name of the manufacturer for this item	"Ben's Manufacturing"
manufacturerPartNumber	string?	Manufacturer part number for this item (MPN)	"54363457"
notes	string?	Additional handwritten details attached to this item	"Brand/Model subs ok"
universalProductCode	string?	Universal product code for this item (UPC)	"54363457"
vendorPartNumber	string?	Part number for this item in the vendor's catalog	"54363457"
needByDate	DateTime?	When this item is needed by	"2021-03-24 17:26:46.983Z"
unitDiscount	float?	Discount percent being applied to the item (precision of 13)	1.25
unitPrice	float?	Unit price of the item	1.25
backorderLeadTime	DateTime?	Lead time for a backordered item	"2021-03-24 17:26:46.983Z"
backorderQuantity	float?	Amount on backorder for a backordered item	10.0
taxCode	string?	The tax code for this item	"07"
catalogId	string?	The catalog id for this item	"ckmnpybisiy5x08abky4g2d1f"
bomItemId	ID?	The ID of the BillOfMaterialsItem for this order item	"ckmnpybisiy5x08abky4g2d1f"
requisitionItemIds	ID[]?	The IDs of any Requisition Items that this PO Item is sourced from	["ckmnpybisiy5x08abky4g2d1f"]

REST Endpoints

GET /orders

Read all orders, with pagination.

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: createdAt, flaggedAt, id, needByDateDay, purchaseOrderNumber, updatedAt.

Allowed filter fields: createdAt, flagged, flaggedAt, id, integrationState_in, mode, needByDateDay, purchaseOrderNumber, state, taxExempt, type, updatedAt.

Response

A list of Order objects.

Example Request

GET https://api.kojo.tech/orders

Example Response

[
  {
    "createdAt": "2020-06-10T07:37:03.651Z",
    "deliveryInstructions": null,
    "discount": null,
    "fieldContactName": "Dwight Schrute",
    "fieldContactPhone": "415-229-2200",
    "flagged": false,
    "flaggedAt": null,
    "flagMessage": null,
    "id": "ckb91ig8400d307335u4p92lq",
    "integrationLastSync": "2020-06-10T07:37:03.633Z",
    "integrationMessage": null,
    "integrationState": "NOT_LINKED",
    "mode": "ISSUE_PO",
    "needByDateDay": "2020-06-10T07:37:03.633Z",
    "needByWindow": "ASAP",
    "purchaseOrderNumber": "75354164",
    "notes": null,
    "shippingCost": null,
    "state": "DRAFT",
    "taxExempt": false,
    "type": "STANDARD",
    "updatedAt": "2020-06-10T07:37:03.651Z"
  }
]

Example Request With Filtering

GET https://api.kojo.tech/orders?filter.purchaseOrderNumber_starts_with=253&filter.state=ACTIVE&filter.createdAt_gt=2020-06-09T07:37:03

Example Response

[
  {
    "createdAt": "2020-06-10T07:37:03.651Z",
    "deliveryInstructions": null,
    "discount": null,
    "fieldContactName": "Dwight Schrute",
    "fieldContactPhone": "415-229-2200",
    "flagged": false,
    "flaggedAt": null,
    "flagMessage": null,
    "id": "ckb91ig8400d307335u4p92lq",
    "integrationLastSync": "2020-06-10T07:37:03.633Z",
    "integrationMessage": null,
    "integrationState": "NOT_LINKED",
    "mode": "ISSUE_PO",
    "needByDateDay": "2020-06-10T07:37:03.633Z",
    "needByWindow": "ASAP",
    "purchaseOrderNumber": "25354164",
    "notes": null,
    "shippingCost": null,
    "state": "ACTIVE",
    "taxExempt": false,
    "type": "STANDARD",
    "updatedAt": "2020-06-10T07:37:03.651Z"
  }
]

GET /orders/:id

Reads a single order by ID. Note that orders can only be uniquely identified by this ID, as it is possible to have draft or cancelled orders with duplicated PO#'s.

Parameters

Name	Description	Example
id	The ID of the order to fetch	"ckmnpybisiy5x08abky4g2d1f"

Response

A single Order.

Example Request

GET https://api.kojo.tech/orders/ckb91ig8400d307335u4p92lq

Example Response

{
  "createdAt": "2020-06-10T07:37:03.651Z",
  "deliveryInstructions": null,
  "discount": null,
  "fieldContactName": "Dwight Schrute",
  "fieldContactPhone": "415-229-2200",
  "flagged": false,
  "flaggedAt": null,
  "flagMessage": null,
  "id": "ckb91ig8400d307335u4p92lq",
  "integrationLastSync": "2020-06-10T07:37:03.633Z",
  "integrationMessage": null,
  "integrationState": "NOT_LINKED",
  "mode": "ISSUE_PO",
  "needByDateDay": "2020-06-10T07:37:03.633Z",
  "needByWindow": "ASAP",
  "purchaseOrderNumber": "75354164",
  "notes": null,
  "shippingCost": null,
  "state": "DRAFT",
  "taxExempt": false,
  "type": "STANDARD",
  "updatedAt": "2020-06-10T07:37:03.651Z"
}

GET /order/buyerId/:buyerId/purchaseOrderNumber/:purchaseOrderNumber

Returns a single order by purchase order number. Only looks for an order for the seller related to the request context and the buyer id that is passed into the request url. This endpoint will also find an order based off an exact match to a provided purchase order number, or a "fuzzy" match on any part of the provided purchase order number based of removal of whitespace, hyphens, slashes, etc. It will only find orders that were updated within 180 days of today.

Parameters

Name	Description	Example
buyerId	The ID of the buyer org	"ckmnpybisiy5x08abky4g2d1f"
purchaseOrderNumber	The purchaseOrderNumber	"1234"

Response

A single Order.

Example Request

GET https://api.kojo.tech/orders/buyerId/ckb91ig8400d307335u4p92lq/purchaseOrderNumber/1234

Example Response

{
  "createdAt": "2020-06-10T07:37:03.651Z",
  "deliveryInstructions": null,
  "discount": null,
  "fieldContactName": "Dwight Schrute",
  "fieldContactPhone": "415-229-2200",
  "flagged": false,
  "flaggedAt": null,
  "flagMessage": null,
  "id": "ckb91ig8400d307335u4p92lq",
  "integrationLastSync": "2020-06-10T07:37:03.633Z",
  "integrationMessage": null,
  "integrationState": "NOT_LINKED",
  "mode": "ISSUE_PO",
  "needByDateDay": "2020-06-10T07:37:03.633Z",
  "needByWindow": "ASAP",
  "purchaseOrderNumber": "75354164",
  "notes": null,
  "shippingCost": null,
  "state": "DRAFT",
  "taxExempt": false,
  "type": "STANDARD",
  "updatedAt": "2020-06-10T07:37:03.651Z"
}

GET /orders/:id/items

Read the items associated with an order.

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: backorderLeadTime, createdAt, id, lineNumber, needByDate, universalProductCode, updatedAt

Default (direction, orderBy): (lineNumber, ASC)

Allowed filter fields: backorderLeadTime, createdAt, id, needByDate, universalProductCode, updatedAt, vendorPartNumber.

Response

A list of Item objects.

Example Request

GET https://api.kojo.tech/orders/ckb91ig8400d307335u4p92lq/items

Example Response

[
  {
    "backorderLeadTime": null,
    "backorderQuantity": null,
    "createdAt": "2020-06-10T07:37:04.646Z",
    "description": "3/4 inch",
    "extPrice": null,
    "id": "ckb91igzt01e90733giki0v0p",
    "lineNumber": 1,
    "manufacturer": null,
    "manufacturerPartNumber": "",
    "needByDate": null,
    "notes": null,
    "quantity": 2000,
    "unitDiscount": null,
    "unitPrice": null,
    "unitsOfMeasure": "ft",
    "universalProductCode": null,
    "updatedAt": "2020-06-10T07:37:04.646Z",
    "orderId": "ckb91ig8400d307335u4p92lq",
    "vendorPartNumber": "12634534"
  }
]

Example Request With Filtering

GET https://api.kojo.tech/orders/ckb91ig8400d307335u4p92lq/items?filter.vendorPartNumber_starts_with=33

Example Response

[
  {
    "backorderLeadTime": null,
    "backorderQuantity": null,
    "createdAt": "2020-06-10T07:37:04.646Z",
    "description": "3/4 inch",
    "extPrice": null,
    "id": "ckb91igzt01e90733giki0v0p",
    "lineNumber": 1,
    "manufacturer": null,
    "manufacturerPartNumber": "",
    "needByDate": null,
    "notes": null,
    "quantity": 2000,
    "unitDiscount": null,
    "unitPrice": null,
    "unitsOfMeasure": "ft",
    "universalProductCode": null,
    "updatedAt": "2020-06-10T07:37:04.646Z",
    "orderId": "ckb91ig8400d307335u4p92lq",
    "vendorPartNumber": "330145"
  }
]

GET /orders/:id/deliveries

Read the deliveries associated with an order.

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: identifier, id, notes, state, createdAt, updatedAt, archivedAt

Default (direction, orderBy): (lineNumber, ASC)

Allowed filter fields: identifier, id, notes, state, createdAt, updatedAt, archivedAt.

Response

A list of Deliveries objects.

Example Request

GET https://api.kojo.tech/orders/ckb91ig8400d307335u4p92lq/deliveries

Example Response

[
  {
    "id": "clr8adymd000112nocbtsetzx",
    "identifier": "DLV-A0001",
    "notes": null,
    "createdAt": "2024-01-10T21:22:26.053Z",
    "archivedAt": null,
    "updatedAt": "2024-01-10T21:22:34.850Z",
    "state": "SUBMITTED"
}
]

POST /orders/:id/updateOrderIntegrationState

Update order's integration status.

Because of the potential complexity involved, an order's integrationState may not be updated via the standard order update endpoint. Instead, use this endpoint to modify the status of the integration link.

See the Integration Status Handling page for more information.

Parameters

Name	Type	Description	Example
id	ID	Unique identifier for orders	"ckmnpybisiy5x08abky4g2d1f"
integrationMessage	string?	A message about the status of the integration's sync	"PO number already exists"
integrationState	IntegrationState	The new status of the order's sync to your integrated system	NOT_LINKED

Example Request

POST https://api.kojo.tech/orders/ckb91ig8400d307335u4p92lq/updateOrderIntegrationState
{
  "integrationState": "LINKED",
  "integrationMessage": ""
}

Example Response

{
  "createdAt": "2020-06-10T07:37:03.651Z",
  "deliveryInstructions": null,
  "discount": null,
  "fieldContactName": "Dwight Schrute",
  "fieldContactPhone": "415-229-2200",
  "flagged": false,
  "flaggedAt": null,
  "flagMessage": null,
  "id": "ckb91ig8400d307335u4p92lq",
  "integrationLastSync": "2020-06-10T07:37:03.633Z",
  "integrationMessage": "",
  "integrationState": "LINKED",
  "mode": "ISSUE_PO",
  "needByDateDay": "2020-06-10T07:37:03.633Z",
  "needByWindow": "ASAP",
  "purchaseOrderNumber": "75354164",
  "notes": null,
  "shippingCost": null,
  "state": "DRAFT",
  "taxExempt": false,
  "type": "STANDARD",
  "updatedAt": "2020-06-10T07:37:03.651Z"
}

POST /order

Create an Order

This endpoint is still in trial, so if you're interested in using it, please reach out to us!

Parameters

Name	Type	Description
orderInput	OrderInput	Input fields for this order
itemInputs	ItemInput[]	Items for this order

Example Request

POST https://api.kojo.tech/order
{
  "orderInput" : {
    "fieldContactName": "John Doe",
    "fieldContactPhone": "800-185-4367",
    "purchaseOrderNumber": "PO-1234",
    "needByDateDay": "2021-03-24 17:26:46.983Z",
    "needByWindow": "AMEarly",
    "deliveryInstructions": "Gate code is 1234",
    "distributorContactName": "Jane Distributor",
    "distributorContactEmail": "jane@distributor.com",
    "distributorContactPhone": "800-185-4367",
    "distributorCompanyName": "Electric Supply Co.",
    "jobId": "clip0pko60142q9upizqo6cpn",
    "requisitionIds": ["clo90qvh9000008mlb89d9r0c"],
    "vendorId": "clkpv7q2v0000q96qk45m84y5",
    "deliveryLocationId": "clip0pkpl014tq9up1c9voj3v",
    "title": "Extra Conduit Order",
    "createdById": "clip0pk82006aq9up7vbr3v72",
    "state": "ACTIVE"
  },
  "itemInputs": [
    {
      "lineNumber": 1,
      "quantity": 20,
      "unitPrice": 10.00,
      "unitsOfMeasure": "EA",
      "description": "EMT Conduit",
      "taxCode": "07",
      "manufacturer": "ESC"
    },
    {
      "lineNumber": 2,
      "quantity": 10,
      "unitPrice": 5.00,
      "unitsOfMeasure": "FT",
      "description": "Blue Wire",
      "notes": "Brand/Model subs ok",
      "manufacturer": "ESC"
    }
  ]
}

Example Response

{
  "createdAt": "2023-08-08T21:02:51.004Z",
  "deliveryInstructions": "Gate code is 1234",
  "deliveryLocationId": "clip0pkpl014tq9up1c9voj3v",
  "discount": null,
  "fieldContactName": "John Doe",
  "fieldContactPhone": "800-185-4367",
  "flagged": false,
  "flaggedAt": null,
  "flagMessage": null,
  "id": "cll2sfqm30007rhyvriqmbubg",
  "jobId": "clip0pko60142q9upizqo6cpn",
  "mode": "ISSUE_PO",
  "needByDateDay": "2021-03-24T17:26:46.983Z",
  "needByWindow": "AMEarly",
  "purchaseOrderNumber": "PO-1234",
  "notes": null,
  "shippingCost": null,
  "state": "DRAFT",
  "type": "STANDARD",
  "updatedAt": "2023-08-08T21:02:51.004Z",
  "vendorId": "clkpv7q2v0000q96qk45m84y5",
  "total": 250,
  "title": "Extra Conduit Order",
  "state": "ACTIVE"
}

POST /orders/:id/cancelOrder

Cancel an Order

This endpoint updates an Order's state to "cancelled".

Parameters

Name	Type	Description
id	ID	ID for the order to cancel
cancelledByUserId	ID	ID for the user who is cancelling the order

Example Request

POST https://api.kojo.tech/orders/clndjblx4000008mf5m8uekwt/cancelOrder?cancelledByUserId=clndjbp29000108mfdzfp8vb6

Example Response

{
  "createdAt": "2023-08-08T21:02:51.004Z",
  "deliveryInstructions": "Gate code is 1234",
  "deliveryLocationId": "clip0pkpl014tq9up1c9voj3v",
  "discount": null,
  "fieldContactName": "John Doe",
  "fieldContactPhone": "800-185-4367",
  "flagged": false,
  "flaggedAt": null,
  "flagMessage": null,
  "id": "clndjblx4000008mf5m8uekwt",
  "jobId": "clip0pko60142q9upizqo6cpn",
  "mode": "ISSUE_PO",
  "needByDateDay": "2021-03-24T17:26:46.983Z",
  "needByWindow": "AMEarly",
  "purchaseOrderNumber": "PO-1234",
  "notes": null,
  "shippingCost": null,
  "state": "CANCELLED",
  "type": "STANDARD",
  "updatedAt": "2023-08-08T21:02:51.004Z",
  "vendorId": "clkpv7q2v0000q96qk45m84y5",
  "total": 250,
  "title": "Extra Conduit Order",
}

GET /orders/:id/attachments

Read the attachments associated with an order.

Response

A list of Attachments objects.

Example Request

GET https://api.kojo.tech/orders/ckb91ig8400d307335u4p92lq/attachments

Example Response

[
    {
        "id": "cm23guhvw000218w1wxk1k7u2",
        "createdAt": "2024-10-10T15:41:10.028Z",
        "updatedAt": "2024-10-10T15:41:10.028Z",
        "identifier": "cl14027710164zrphaixf088l.pdf",
        "file": {
            "id": "cm23gufwn000018w19f335wln",
            "name": "cl14027710164zrphaixf088l.pdf",
            "createdAt": "2024-10-10T15:41:07.462Z",
            "updatedAt": "2024-10-10T15:41:07.462Z",
            "url": "https://agora-uploads-dev.s3.us-west-2.amazonaws.com/2dcbe73e-c00c-5f50-9e28-d20f8d7dbca6/cl14027710164zrphaixf088l.pdf"
        }
    }
]

GET /orders/:orderId/tags

See Get Order Tags for more information.

POST /orders/:orderId/tags

See Add Tags to Order for more information.

DELETE /orders/:orderId/tags

See Remove Tag From Order for more information.