Change Orders

Each time you create a Change Order on a Purchase Order in Kojo, a new Order Version is created. These versions are numbered sequentially, with the initial Order being defined as Version 0. A Change Order is considered to be a Draft until the Complete this Change Order button is pressed. Drafts will be ignored.

Schema

`ChangeOrder`

Name	Type	Description	Example
id	`ID`	Unique identifier for Change Order	`"ckmnpybisiy5x08abky4g2d1f"`
createdAt	`DateTime`	When this Change Order was created	`"2024-03-24 17:26:46.983Z"`
createdById	`ID`	The user id who created this Change Order	`"clsntgbse000008l46x9h2kme"`
orderId	`ID`	Unique identifier for Order	`"cldccq7ah0003lg6jnh8xhl01"`
label	`string?`	Label given to Change Order	`"Adjust Unit Price"`
note	`string?`	Note applied to Change Order	`"The vendor told us that we could take 10% off the unit price."`
versionNumber	`int`	Number assigned to Change Order	`4`
modifiedOrderValues	JSON - Subset of `OrderDiff`	Order values that have been mutated in this Change Order.	See below.
addedItems	JSON Array - `ItemDiff`	Any order items that been added within this Change Order.	See below.
deletedItems	JSON Array - `ItemDiff`	Any order items that have been deleted in this Change Order.	See below.
modifiedItems	JSON Array - Subset of `ItemDiff`	Values from already existing order items that have been mutated in this Change Order.	See below.

`OrderDiff`

The modifiedOrderValues JSON object will only return order values that have changed in this Change Order compared to the prior Change Order. If a key in the modifiedOrderValues JSON is assigned a null, it can be assumed that the field's value was deleted in this Change Order.

Name	Type	Description	Example
id	`ID`	Unique identifier for the order	`"ckmnpybisiy5x08abky4g2d1f"`
createdAt	`DateTime`	When the order was created	`"2024-03-24 17:26:46.983Z"`
customColumnValue	`string?`	Value associated with the custom column	`"438076873"`
deliveryInstructions	`string?`	Additional instructions for how to deliver the items	`"Gate code is 1234"`
deliveryLocationId	`ID?`	Delivery location ID for this 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"`
glCodeId	`ID?`	The ID of 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"`
integrationState	`IntegrationState?`	The status of the order's sync to another integrated system	`NOT_LINKED`
jobId	`ID?`	The id for the job this order belongs to	See Job docs
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	`PMLate`
notes	`string?`	Additional handwritten details attached to this order	`"Call when arrives"`
purchaseOrderNumber	`string?`	User-defined value to identify this order	`"1234"`
receivedState	`ReceivedState?`	The state of the deliveries associated with the PO	`"FULLY_RECEIVED"`
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`
taxCodeId	`ID?`	The ID of 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`
total	`float?`	The total due for the order	`184.33`
type	`OrderType?`	Type of order, either `STANDARD` or `HOLD_FOR_RELEASE`	`STANDARD`
updatedAt	`DateTime`	When the order was last updated	`"2024-03-24 17:26:46.983Z"`
vendorId	`ID?`	The vendorId associated with this order	See Vendor docs

`ItemDiff`

The modifiedItems JSON array will only return item values that have been mutated in this Change Order. If a key in modifiedItems is assigned a null value, it can be assumed that the corresponding value was deleted in this Change Order. modifiedItems will always contain id, lineNumber, createdAt, and updatedAt.

The addedItems and deletedItems arrays will always contain all of the keys listed in this schema.

Name	Type	Description	Example
id	`ID`	Unique identifier for this item	`"ckmnpybisiy5x08abky4g2d1f"`
backorderLeadTime	`DateTime?`	Lead time for a backordered item	`"2024-03-24 17:26:46.983Z"`
backorderQuantity	`float?`	Amount on backorder for a backordered item	`20.0`
costCategory	`string?`	Cost Category code of the item	`"M"` - See Cost Category docs
createdAt	`DateTime`	When this item was created	`"2024-03-24 17:26:46.983Z"`
customColumnValue	`string?`	Value associated with the custom column	`"438076873"`
description	`string?`	Description of the item	`"3/4" EMT"`
extPrice	`float?`	EXT Price of the item	`125.00`
itemCodeId	`ID?`	ID of the Item Code for the item	`"ckmnpybisiy5x08abky4g2d1f"`
lineNumber	`int`	Number representing the index of the line item within it's order	`3`
manufacturer	`string?`	Name of the manufacturer for this item	`"Marcus Manufacturing"`
manufacturerPartNumber	`string?`	Manufacturer part number for this item (MPN)	`"267254567"`
needByDate	`DateTime?`	When this item is needed by	`"2024-03-24 17:26:46.983Z"`
notes	`string?`	Additional handwritten details attached to this item	`"Requested ASAP"`
phase	`string?`	Phase Code of the item	`"Rough-in"` - See Phase docs
quantity	`float?`	Quantity of this item	`100.0`
taxCode	`string?`	Tax code of the item	`"NYC"` - See Tax Code docs
taxRate	`float?`	Tax rate of the item	`0.025` - See Tax Code docs
unitDiscount	`float?`	Discount being applied to the item (precision of 13)	`1.25`
unitPrice	`float?`	Unit price of the item	`1.25`
unitsOfMeasure	`string?`	Unit of measurement for this item	`"EA"`
universalProductCode	`string?`	Universal product code for this item (UPC)	`"037000282525"`
updatedAt	`DateTime`	When this item was last updated	`"2024-03-24 17:26:46.983Z"`
vendorPartNumber	`string?`	Part number for this item in the vendor's catalog	`"73595677"`

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.

Queries

`changeOrder`

Gets a specific Change Order by ID.

Parameters

Name	Type	Description	Example
changeOrderId	`ID`	Unique identifier for Change Order	`"ckmnpybisiy5x08aasdf13242"`

Response

A ChangeOrder object.

Example Query

query {
  changeOrder (changeOrderId: "ckmnpybisiy5x08aasdf13242") {
    id
    createdAt
    orderId
    label
    note
    versionNumber

    modifiedOrderValues
    addedItems
    deletedItems
    modifiedItems
  }
}

Example Response

{
  "id": "ckmnpybisiy5x08aasdf13242",
  "createdAt": "2024-01-25 17:26:46.983Z",
  "orderId": "cls0zixkq004jjc1pjy8bwvt5",
  "label": "Marcus's Change Order",
  "note": "This was requested by Phillip.",
  "versionNumber": "5",
  "modifiedOrderValues": {
    "shippingCost": 123.45,
    "notes": "Please process ASAP",
    "glCodeId": null
  },
  "addedItems": [
    {
      "id": "cls9lapp1000oa17uwim720lz",
      "createdAt": "2024-02-06T00:06:59.632Z",
      "updatedAt": "2024-02-06T00:06:59.632Z",
      "backorderLeadTime": null,
      "backorderQuantity": null,
      "costCategory": "L",
      "customColumnValue": null,
      "description": "RT EMT CONN",
      "extPrice": 40,
      "itemCodeId": null,
      "lineNumber": 5,
      "manufacturer": null,
      "manufacturerPartNumber": null,
      "needByDate": null,
      "notes": null,
      "phase": "1-002",
      "quantity": 2,
      "taxCode": "OR",
      "taxRate": 0.025,
      "unitDiscount": null,
      "unitPrice": 20,
      "unitsOfMeasure": "EA",
      "universalProductCode": null,
      "vendorPartNumber": null
    }
  ],
  "deletedItems": [],
  "modifiedItems": [
    {
      "id": "cjzu0wx37o1cs0985gp2y4qn2",
      "lineNumber": 3,
      "createdAt": "2024-01-06 17:26:46.983Z",
      "updatedAt": "2024-01-25 17:26:46.983Z",
      "description": "CHANNEL SUPPORT"
    },
    {
      "id": "cjzu2j4n0pnt30985f1o18rfa",
      "lineNumber": 4,
      "createdAt": "2024-01-06 17:26:46.983Z",
      "updatedAt": "2024-01-26 17:26:46.983Z",
      "quantity": 15,
      "extPrice": 376.12
    },
  ],
}

`changeOrders`

This endpoint provides a feed of any Change Orders that have been created for a given organization.

This endpoint only returns up to 10 ChangeOrders at a time.

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: createdAt, updatedAt.

Allowed filter fields: createdAt, id, orderId, updatedAt.

Response

A list of ChangeOrder objects.

Example Query

query {
  changeOrders {
    id
    createdAt
    orderId
    label
    note
    versionNumber

    modifiedOrderValues
    addedItems
    deletedItems
    modifiedItems
  }
}

Example Response

[
  {
    "id": "ckmnpybisiy5x08aasdf13242",
    "createdAt": "2024-01-25 17:26:46.983Z",
    "orderId": "cls0zixkq004jjc1pjy8bwvt5",
    "label": "Marcus's Change Order",
    "note": "This was requested by Phillip.",
    "versionNumber": "5",
    "modifiedOrderValues": {
      "shippingCost": 123.45,
      "notes": "Please process ASAP",
      "glCodeId": null
    },
    "addedItems": [
      {
        "id": "cls9lapp1000oa17uwim720lz",
        "createdAt": "2024-02-06T00:06:59.632Z",
        "updatedAt": "2024-02-06T00:06:59.632Z",
        "backorderLeadTime": null,
        "backorderQuantity": null,
        "costCategory": "L",
        "customColumnValue": null,
        "description": "RT EMT CONN",
        "extPrice": 40,
        "itemCodeId": null,
        "lineNumber": 5,
        "manufacturer": null,
        "manufacturerPartNumber": null,
        "needByDate": null,
        "notes": null,
        "phase": "1-002",
        "quantity": 2,
        "taxCode": "OR",
        "taxRate": 0.025,
        "unitDiscount": null,
        "unitPrice": 20,
        "unitsOfMeasure": "EA",
        "universalProductCode": null,
        "vendorPartNumber": null
      }
    ],
    "deletedItems": [],
    "modifiedItems": [
      {
        "id": "cjzu0wx37o1cs0985gp2y4qn2",
        "lineNumber": 3,
        "createdAt": "2024-01-06 17:26:46.983Z",
        "updatedAt": "2024-01-25 17:26:46.983Z",
        "description": "CHANNEL SUPPORT"
      },
      {
        "id": "cjzu2j4n0pnt30985f1o18rfa",
        "lineNumber": 4,
        "createdAt": "2024-01-06 17:26:46.983Z",
        "updatedAt": "2024-01-26 17:26:46.983Z",
        "quantity": 15,
        "extPrice": 376.12
      },
    ],
  },
  {
    "id": "cls9l9hxy0007c73h4o4desrz",
    "createdAt": "2024-01-30 17:26:46.983Z",
    "orderId": "cls9l9vph000na17ucnn8h72s",
    "label": "Bob's Change Order",
    "note": "This was requested by Henderson.",
    "versionNumber": "3",
    "modifiedOrderValues": {
      "shippingCost": 123.45,
      "notes": "Please process ASAP",
      "glCodeId": null
    },
    "addedItems": [],
    "deletedItems": [
      {
        "id": "cls9lapp1000oa17uwim720lz",
        "createdAt": "2024-02-06T00:06:59.632Z",
        "updatedAt": "2024-02-06T00:06:59.632Z",
        "backorderLeadTime": null,
        "backorderQuantity": null,
        "costCategory": "L",
        "customColumnValue": null,
        "description": "Junction Boxes",
        "extPrice": 2,
        "itemCodeId": null,
        "lineNumber": 5,
        "manufacturer": null,
        "manufacturerPartNumber": null,
        "needByDate": null,
        "notes": null,
        "phase": "1-005",
        "quantity": 2,
        "taxCode": "OR",
        "taxRate": 0.025,
        "unitDiscount": null,
        "unitPrice": 4,
        "unitsOfMeasure": "EA",
        "universalProductCode": null,
        "vendorPartNumber": null
      }
    ],
    "modifiedItems": [
      {
        "id": "cjzu0wx37o1cs0985gp2y4qn2",
        "lineNumber": 10,
        "createdAt": "2024-01-06 17:26:46.983Z",
        "updatedAt": "2024-01-25 17:26:46.983Z",
        "description": "Putty"
      },
      {
        "id": "cjzu2j4n0pnt30985f1o18rfa",
        "lineNumber": 11,
        "createdAt": "2024-01-06 17:26:46.983Z",
        "updatedAt": "2024-01-26 17:26:46.983Z",
        "quantity": 6,
        "extPrice": 76.12
      },
    ],
  }
]

Mutations

`updateOrderVersionIntegrationState`

Updates the integrationState of a Change Order.

See the Integration Status Handling page for more information.

Parameters

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

Response

A boolean indicating success.

Example Query

mutation {
  updateOrderVersionIntegrationState(
    changeOrderId: "ckmnpybisiy5x08abky4g2d1f",
    integrationState: "LINKED",
    integrationMessage: ""
  )
}

Example Response

true

Schema​

ChangeOrder​

OrderDiff​

ItemDiff​

Enums​

IntegrationState​

Queries​

changeOrder​

Parameters​

Response​

Example Query​

Example Response​

changeOrders​

Parameters​

Response​

Example Query​

Example Response​

Mutations​

updateOrderVersionIntegrationState​

Parameters​

Response​

Example Query​

Example Response​

Schema

`ChangeOrder`

`OrderDiff`

`ItemDiff`

Enums

`IntegrationState`

Queries

`changeOrder`

Parameters

Response

Example Query

Example Response

`changeOrders`

Parameters

Response

Example Query

Example Response

Mutations

`updateOrderVersionIntegrationState`

Parameters

Response

Example Query

Example Response