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"
createdBy	User	❌ Not implemented The user who created the order	See User docs
deliveryInstructions	string?	Additional instructions for how to deliver the items	"Gate code is 1234"
deliveryLocation	Location?	Delivery location for order	See Location docs
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	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
job	Job?	The job this order belongs to	See Job docs
mode	OrderMode	The mode the order originated in	REQUEST_FOR_QUOTE
attachments	OrderAttachment[]	The attachments associated with the order	See OrderAttachment[]
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	PMLate
notes	string?	Additional handwritten details attached to this order	"Call when arrives"
purchaseOrderNumber	string?	User-defined value to identify this order	"1234"
purchasingAgent	User	❌ Not implemented User at buyer organization responsible for reconciling the order	See User docs
items	Item[]	The line items in the order	See Item docs
requisitionIds	ID[]?	The IDs of any Requisitions that this Order is sourced from	["ckmnpybisiy5x08abky4g2d1f"]
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_ACTIVE
taxCode	TaxCode?	The default tax code to use for items in this order	See Tax Code docs
taxExempt	boolean	Indicates that the order is exempt from any and all tax rates entered on line items	true
type	OrderType	Type of order, either STANDARD or HOLD_FOR_RELEASE	STANDARD
updatedAt	DateTime	When this order was last updated	"2021-03-24 17:26:46.983Z"
updatedBy	User?	❌ Not implemented The user who last edited the order	See User docs
vendor	Vendor?	The vendor associated with this order	See Vendor docs
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"
hasDraftChangeOrder	boolean	Indicates if the order has a currently open draft change order	true

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.

Note: The only Scalar Filter that IntegrationState currently supports is integrationState_in.

ReceivedState

Value	Description
NO_DELIVERIES	No deliveries submited yet.
PARTIALLY_RECEIVED	Deliveries were submited 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.
lastSyncAt	DateTime	The date and time when the attachment was last synced	"2024-09-03T12:00:00Z"
syncedBy	string	A service name which performed the sync	"api-sync-order-attachments"

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	"Expedite please"
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"
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
unitsOfMeasure	string?	Unit of measurement for this item	"BX"
description	string?	Description of the item	"3/4 in EMT"
manufacturer	string?	Name of the manufacturer for this item	"Bob's Manufacturing"
manufacturerPartNumber	string?	Manufacturer part number for this item (MPN)	"3456377"
notes	string?	Additional handwritten details attached to this item	"Brand/Model subs ok"
universalProductCode	string?	Universal product code for this item (UPC)	"037000754770"
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	50
taxCode	string?	The tax code for this item	"07"
catalogId	string?	The catalog id for this item	"clopaavoh000hrdr3yag0soz8"
bomItemId	ID?	The ID of the BillOfMaterialsItem for this order item	"ckmnpybisiy5x08abky4g2d1f"

Queries

order

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 Query

query {
  order(id: "ckmnpybisiy5x08abky4g2d1f") {
    id
    purchaseOrderNumber
  }
}

Example Response

{
  "id": "ckmnpybisiy5x08abky4g2d1f",
  "purchaseOrderNumber": "606123",
}

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 Query

query {
  orders(
    orderBy: purchaseOrderNumber,
    direction: ASC,
    filter: {
        createdAt_lt: "2024-01-01T15:10:10"
    }
  ) {
    id
    purchaseOrderNumber
    createdAt
  }
}

Example Response

[
  {
    "id": "ckmnpybisiy5x08aasdf13242",
    "purchaseOrderNumber": "111444",
    "createdAt": "2023-01-26T16:18:35.931Z"
  },
  {
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "purchaseOrderNumber": "606123",
    "createdAt": "2023-01-26T16:49:04.773Z"
  }
]

getOrderTags

See getOrderTags for more information.

Mutations

updateOrderIntegrationState

Update an 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 Query

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

Example Response

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

createOrder

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

Response

The created Order.

Example Query

mutation {
  createOrder(
    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",
      requisitionId: "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",
      }
    ]

  ) {
        id
    purchaseOrderNumber
    vendor {
      name
    }
    deliveryLocation {
      addressLine1
      state
      zipcode
    }
    items {
      description
    }
  }
}

Example Response

{
  "id": "cll2r2kf60004rhyvd0nm7tq2",
  "purchaseOrderNumber": "PO-1234",
  "state": "ACTIVE",
  "vendor": {
    "name": "ELECTRIC SUPPLY INC"
  },
  "deliveryLocation": {
    "addressLine1": "780 S Airport Blvd",
    "state": "CA",
    "zipcode": "94128"
  },
  "items": [
    {
      "description": "EMT Conduit"
    },
    {
      "description": "Blue Wire"
    }
  ]
}

cancelOrder

Cancel an Order

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

Parameters

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

Response

The updated (cancelled) Order.

Example Query

mutation {
  cancelOrder(
    orderId: "clndjblx4000008mf5m8uekwt",
    cancelledByUserId: "clndjbp29000108mfdzfp8vb6"
  ) {
    id
    purchaseOrderNumber
    state
  }
}

Example Response

{
  "id": "clndjblx4000008mf5m8uekwt",
  "purchaseOrderNumber": "PO-1234",
  "state": "CANCELLED"
}

addNewOrExistingTagsToOrder

See addNewOrExistingTagsToOrder for more information.

removeTagFromOrder

See removeTagFromOrder for more information.

syncAttachment

Synchronize an attachment with the order.

Currently, this endpoint is only supported for Spectrum Cloud. This endpoint allows you to sync an attachment to an existing order, ensuring that the attachment is properly associated with the order in the system.

Parameters

Name	Type	Description	Example
orderId	ID	ID of the order to which the attachment will be synced	"clndjblx4000008mf5m8uekwt"

Response

The updated OrderAttachment with the synced attachment.

Example Query

mutation syncOrderAttachments($orderId: ID!){
    syncOrderAttachments(orderId: $orderId){
        id
        createdAt
        updatedAt
        identifier
        syncedBy
        lastSyncAt
    }
}

Example Response

{
    "data": {
        "syncOrderAttachments": [
            {
                "id": "cm66rsgb40002v7ve0x5tjbbm",
                "createdAt": "2025-01-21T17:49:38.320Z",
                "updatedAt": "2025-01-21T23:02:35.678Z",
                "identifier": "S-0117-P1.pdf",
                "lastSyncAt": "2025-01-21T23:02:35.677Z",
                "syncedBy": "api-sync-order-attachments"
            }
        ]
    }
}