Acknowledgements

REST Endpoints

POST /order/:orderId/acknowledge

Behavior by Order Type

The order must be in OPEN state. The MAJOR-only item fields (area, designationType, isLot, productCategory) are accepted on MAJOR orders only and rejected on STANDARD and HOLD_FOR_RELEASE.

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 item fields used on non-MAJOR order	INTEGRATION_API_CREATE_ORDER_ACKNOWLEDGEMENT_MAJOR_ONLY_FIELDS
Top-level sellerMetadata is not an object	INTEGRATION_API_CREATE_ORDER_ACKNOWLEDGEMENT_INVALID_SELLER_METADATA

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
sellerMetadata	object?	Optional metadata object for seller-side order tracking. See Order Seller Metadata.	{"sellerOrderId": "S-9000"}

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?	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.

Order Seller Metadata

The top-level sellerMetadata object can contain arbitrary key-value pairs for seller-side order tracking. Accepted on every order type.

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
sellerMetadata	object?	The order-level seller metadata that was persisted on the acknowledgement
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
{
  "sellerMetadata": {
    "sellerOrderId": "S-9000"
  },
  "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",
  "sellerMetadata": {
    "sellerOrderId": "S-9000"
  },
  "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"
    }
  ]
}