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"
deliveryInstructions	string?	Additional instructions for how to deliver the items	"Gate code is 1234"
deliveryLocation	Location?	Delivery location for order
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"
needByDateDay	DateTime?	The date the order is needed by
needByWindow	NeedByWindow	Window the order should be delivered by
notes	string?	Additional handwritten details attached to this order
purchaseOrderNumber	string?	User-defined value to identify this order	"1234"
items	Item[]	The line items in the order
state	OrderState	The current state of the order
buyerId	ID	Unique identifier for the buyer company	"ckmnpybisiy5x08abky4g2d1f"
buyer	string	Buyer company name	"Customer Company name"
taxCodeId	ID	Order tax code identifier
taxExempt	boolean	Indicates that the order is exempt from any and all tax rates entered on line items
createdAt	DateTime	When this order was created
updatedAt	DateTime	When this order was last updated
purchasingAgent	User	❌ Not implemented User at buyer organization responsible for reconciling the order
createdBy	User	❌ Not implemented The user who created the order
updatedBy	User?	❌ Not implemented The user who last edited the order

Enums

NeedByWindow

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

OrderState

Value	Description
OPEN	Order is open to be acknowledged
ACKNOWLEDGED	Orders was acknowledged
CLOSED	Order process is completed

REST Endpoints

GET /orders

Read all orders, with pagination.

Parameters

Accepts all standard pagination parameters.

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

Response

A list of Order objects.

Example Request

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

Example Response

[
  {
    "id": "cl7kgfihx0230bmq4cf0zcr78",
    "purchaseOrderNumber": "j-0902-1",
    "jobId": "cl7g8gxgu4452ccr7ob8ldi43",
    "deliveryLocationId": "cl7g8gxja4641ccr7hhd4czok",
    "fieldContactName": "john",
    "fieldContactPhone": "+5587988461794",
    "needByDateDay": "2022-09-05T07:00:00.000Z",
    "needByWindow": "ASAP / Rush",
    "taxExempt": false,
    "createdAt": "2022-09-02T12:30:43.557Z",
    "updatedAt": "2022-09-02T13:54:30.836Z",
    "state": "OPEN",
    "deliveryLocation": {
      "addressLine1": "780 S Airport Blvd",
      "name": "SFO Terminal 1 - Main",
      "state": "CA",
      "zipcode": "94128",
      "directions": "Follow Terminal 1 departure signs to construction grounds."
    },
    "job": {
      "id": "cl7g8gxgu4452ccr7ob8ldi43",
      "jobCode": "12412426",
      "name": "SFO Terminal 1"
    },
    "items": [
      {
        "id": "cl7kgh2tq3662bmq4je5he31m",
        "lineNumber": 1,
        "quantity": 1,
        "unitsOfMeasure": "EA",
        "createdAt": "2022-09-02T12:31:56.558Z",
        "updatedAt": "2022-09-02T12:32:19.347Z",
        "description": "test item",
        "unitPriceFloat": 10,
        "extPriceFloat": 10
      }
    ],
    "buyer": {
      "id": "cl7g8gwry0451ccr778c2gngo",
      "name": "Dunder Mifflin",
      "customerAccountNumbers": {"send": "TESTCC", "receive": [ "TESTCC" ]},
      "location": {
        "name": "Agora HQ - Receiving",
        "addressLine1": "637 Natoma St.",
        "addressLine2": "#7",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94103",
        "directions": "instructions",
        "phone": "415-623-7898"
      }
    }
  }
]

Example Request with Pagination and Filtering

The following example will return the first 100 orders that are open (to exclude already acknowledged orders) with an offset of 0, that have been updated since 12/15/2023 at 20:15:42 UTC.

GET https://api.kojo.tech/seller/orders?limit=100&offset=0&state=OPEN&updatedAfter=2023-12-15T20:15:42.000Z

GET /order/: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	"cl63u8ez503271lr7stfwx53x"

Response

A single Order.

Example Request

GET https://api.kojo.tech/seller/order/cl63u8ez503271lr7stfwx53x

Example Response

{
  "id": "cl7kgfihx0230bmq4cf0zcr78",
  "purchaseOrderNumber": "j-0902-1",
  "jobId": "cl7g8gxgu4452ccr7ob8ldi43",
  "deliveryLocationId": "cl7g8gxja4641ccr7hhd4czok",
  "fieldContactName": "john",
  "fieldContactPhone": "+5587988461794",
  "needByDateDay": "2022-09-05T07:00:00.000Z",
  "needByWindow": "ASAP / Rush",
  "taxExempt": false,
  "createdAt": "2022-09-02T12:30:43.557Z",
  "updatedAt": "2022-09-02T13:54:30.836Z",
  "state": "OPEN",
  "deliveryLocation": {
    "addressLine1": "780 S Airport Blvd",
    "name": "SFO Terminal 1 - Main",
    "state": "CA",
    "zipcode": "94128",
    "directions": "Follow Terminal 1 departure signs to construction grounds.",
    "phone": "650-382-2251"
  },
  "job": {
    "id": "cl7g8gxgu4452ccr7ob8ldi43",
    "jobCode": "12412426",
    "name": "SFO Terminal 1"
  },
  "items": [
    {
      "id": "cl7kgh2tq3662bmq4je5he31m",
      "lineNumber": 1,
      "quantity": 1,
      "unitsOfMeasure": "EA",
      "createdAt": "2022-09-02T12:31:56.558Z",
      "updatedAt": "2022-09-02T12:32:19.347Z",
      "description": "test item",
      "unitPriceFloat": 10,
      "extPriceFloat": 10
    }
  ],
  "buyer": {
    "id": "cl7g8gwry0451ccr778c2gngo",
    "name": "Dunder Mifflin",
    "phone": "650-382-9052",
    "customerAccountNumbers": {"send": "TESTCC", "receive": [ "TESTCC" ]},
    "location": {
      "name": "Agora HQ - Receiving",
      "addressLine1": "637 Natoma St.",
      "addressLine2": "#7",
      "city": "San Francisco",
      "state": "CA",
      "zipcode": "94103",
      "directions": "instructions",
      "phone": "415-623-7898"
    }
  }
}