Acknowledgements

REST Endpoints

POST /order/:orderId/acknowledge

Behavior by Order Type

Standard orders (STANDARD, HOLD_FOR_RELEASE):

• The order must be in OPEN state.
• MAJOR-only fields (area, designationType, isLot, productCategory, sellerMetadata) are not allowed and will return an error if provided.

Major orders (MAJOR):

• The order must be in OPEN state.
• MAJOR-only fields (area, designationType, isLot, productCategory, sellerMetadata) are allowed.

Error Cases

Scenario	Error Code
Invalid acknowledgement items data	INTEGRATION_API_CREATE_ORDER_ACKNOWLEDGEMENT_INVALID_ACKNOWLEDGEMENT_ITEMS
Order not found	INTEGRATION_API_ORDER_NOT_FOUND
MAJOR order not in OPEN state	INTEGRATION_API_CREATE_ORDER_ACKNOWLEDGEMENT_INVALID_ORDER_STATE
MAJOR-only fields used on non-MAJOR order	INTEGRATION_API_CREATE_ORDER_ACKNOWLEDGEMENT_MAJOR_ONLY_FIELDS

Parameters

Name	Type	Description	Example
orderId (in url)	ID	The ID of the order to which the acknowledgement corresponds	"ckmnpybisiy5x08abky4g2d1f"
acknowledgementItems	AcknowledgementItem[]	An array of acknowledgementItems to be applied to the order's line items	See schema definition below

Acknowledgement Items

Each item on the acknowledgement should have the structure below.

Name	Type	Description	Example
backorderLeadTime	string?	If an item is backordered, the expected lead time	2 days
backorderQuantity	integer?	If an item is backordered, the quantity backordered	5
description	string?	A description of the item	12 gauge black THHN
expectedDeliveryTime	string?	The expected item delivery date	20251220
extPriceFloat	float?	The subtotal of the item	4.50
itemId	ID?	The item's kojo id	cl70xmen80002oodabq9syjlq
lineNumber	integer?	The item's purchase order line number	1
manufacturer	string?	The manufacturer name for the item	"Acme Corp"
manufacturerPartNumber	string?	The manufacturer part number for the item	"MPN-456"
quantity	integer?	The quantity of the item	3
unitPriceECM	string?	Multiplier used to calculate the extended price from the unit price. Must be either E, C, or M. Defaults to E.	"E"
unitPriceFloat	float?	The unit price of the item	1.50
unitsOfMeasure	string	The item's unit of measure	FT
universalProductCode	string?	The items UPC	FT
vendorPartNumber	string?	Your company's SKU for the item	FT
area	string?	⚠️ Major orders only The area or zone for the item	"Zone A"
designationType	string?	⚠️ Major orders only The designation type for the item	"Electrical"
isLot	boolean?	⚠️ Major orders only Whether this item is a lot item. Defaults to false.	true
productCategory	string?	⚠️ Major orders only The product category for the item	"Wire & Cable"
sellerMetadata	object?	⚠️ Major orders only Optional metadata object for seller-side item tracking. See Seller Metadata.	{"itemId": "S-100"}

Seller Metadata

The sellerMetadata object can contain arbitrary key-value pairs. The following properties have special meaning for establishing parent/child item relationships on MAJOR orders:

Name	Type	Description
itemId	string?	A seller-side identifier for this item. Other items can reference this value via parentItemId to create a parent/child hierarchy.
parentItemId	string?	References another item's sellerMetadata.itemId within the same acknowledgement, indicating that this item is a child of that parent item.

When both itemId and parentItemId are provided across acknowledgement items, the system will automatically set the parentItemId on the corresponding order items after they are created. Self-references (where itemId equals parentItemId) are ignored.

Response

The created Acknowledgement object with the following fields:

Name	Type	Description
id	ID	The acknowledgement ID
buyerId	ID	The buyer organization ID
createdAt	string	ISO 8601 timestamp of creation
orderId	ID	The associated order ID
acknowledgementItems	AcknowledgementItem[]	The created acknowledgement items

Each acknowledgement item in the response includes an itemId field. For MAJOR orders (where items are auto-applied), this will be the ID of the newly created order item. For other orders, this reflects the itemId provided in the request, or null if none was provided.

Example Request

POST https://api.kojo.tech/seller/order/cl5vad0wh0315m5lgqvsimj3k/acknowledge
{
  "acknowledgementItems": [
    {
      "itemId": "cl70xmen80002oodabq9syjlq",
      "lineNumber": 1,
      "unitPriceFloat": 100.05,
      "quantity": 2,
      "expectedDeliveryTime": "20260120",
      "extPriceFloat": 200.10,
      "description": "6 Strand Copper Wire Soft Drawn 315'",
      "manufacturer": "Southwire",
      "unitsOfMeasure": "FT",
      "sellerMetadata": {
        "itemId": "S-100"
      }
    },
    {
      "itemId": "cl70xmen80003ooda4hv3my6j",
      "lineNumber": 2,
      "unitPriceFloat": 43.33,
      "quantity": 1,
      "extPriceFloat": 44.33,
      "description": "8 AWG THHN Stranded Copper, Green, 500'",
      "manufacturer": "Cerrowire",
      "unitsOfMeasure": "FT",
      "sellerMetadata": {
        "itemId": "S-200",
        "parentItemId": "S-100"
      }
    }
  ]
}

Example Response

{
  "id": "cl5vad0wh0315m5lgqvsimj3k",
  "buyerId": "cl5vad0wh0315m5lgqvsimj37",
  "createdAt": "2024-05-03T16:22:32.869Z",
  "orderId": "clvphf6dz022c4wu4l15giyw3",
  "acknowledgementItems":  [
    {
      "itemId": "cl70xmen80002oodabq9syjlq",
      "lineNumber": 1,
      "unitPriceFloat": 100.05,
      "quantity": 2,
      "expectedDeliveryTime": "2026-01-20T00:00:00.000Z",
      "extPriceFloat": 200.10,
      "description": "6 Strand Copper Wire Soft Drawn 315'",
      "unitsOfMeasure": "FT"
    },
    {
      "itemId": "cl70xmen80003ooda4hv3my6j",
      "lineNumber": 2,
      "unitPriceFloat": 43.33,
      "quantity": 1,
      "expectedDeliveryTime": null,
      "extPriceFloat": 44.33,
      "description": "8 AWG THHN Stranded Copper, Green, 500'",
      "unitsOfMeasure": "FT"
    }
  ]
}