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 unless explicitly requested in the endpoint parameters.

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`
updatedAt	`DateTime`	When the order was last updated	`"2024-03-24 17:26:46.983Z"`
type	`OrderType?`	Type of order, either `STANDARD` or `HOLD_FOR_RELEASE`	`STANDARD`
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 the 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"`

REST Endpoints

GET `/changeOrders/:changeOrderId`

This endpoint provides a single Change Order by its ID.

Query Parameters

Name	Description	Example
changeOrderId	The ID of the Change Order to fetch	`"ckmnpybisiy5x08abky4g2d1f"`

Response

The ChangeOrder object.

Example Request

GET https://api.kojo.tech/changeOrders/ckmnpybisiy5x08aasdf13242

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
    },
  ],
}

GET `/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.

Query Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: createdAt, updatedAt.

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

Response

A list of ChangeOrder objects.

Example Request

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

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
      },
    ],
  }
]

POST `/changeOrders/:changeOrderId/integrationState`

This endpoint allows you to update the integrationState of a Change Order.

Query Parameters

Name	Type	Description	Example
changeOrderId	`ID`	Unique identifier for change 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 change order's sync to your integrated system	`NOT_LINKED`

Response

A boolean indicating success.

Example Request

POST https://api.kojo.tech/changeOrders/ckmnpybisiy5x08abky4g2d1f/integrationState
{
  "integrationState": "LINKED",
  "integrationMessage": ""
}

Example Response

true

Schema​

ChangeOrder​

OrderDiff​

ItemDiff​

REST Endpoints​

GET /changeOrders/:changeOrderId​

Query Parameters​

Response​

Example Request​

Example Response​

GET /changeOrders​

Query Parameters​

Response​

Example Request​

Example Response​

POST /changeOrders/:changeOrderId/integrationState​

Query Parameters​

Response​

Example Request​

Example Response​

Schema

`ChangeOrder`

`OrderDiff`

`ItemDiff`

REST Endpoints

GET `/changeOrders/:changeOrderId`

Query Parameters

Response

Example Request

Example Response

GET `/changeOrders`

Query Parameters

Response

Example Request

Example Response

POST `/changeOrders/:changeOrderId/integrationState`

Query Parameters

Response

Example Request

Example Response