Skip to main content

Catalog Items

A Catalog Item is one entry in your organization's catalog, identified by your own SKU. Catalog Items written through the API are available only to your organization.

Use GET /catalog-items to keep an external system in sync: page through every result once, store the latest updatedAt you received, and on the next sync pass it as filter.updatedAt_gte.

Schema​

CatalogItem​

NameTypeDescriptionExample
idIDUnique identifier for the catalog item"ckmnpybisiy5x08abky4g2d1f"
skuString?Your organization's unique SKU for the catalog item"EMT-075"
descriptionString?Description of the catalog item"3/4\" EMT Conduit"
nicknameString?The name your organization gave the catalog item"3/4 EMT"
searchTermsString[]Your organization's search terms for the catalog item["conduit", "EMT 3/4"]
manufacturerNameString?Name of the manufacturer"Allied Tube"
manufacturerPartNumberString?The manufacturer part number"101543"
universalProductCodeString?The universal product code"786564101543"
unitsOfMeasureString?The unit of measure for the catalog item"FT"
disabledBooleanWhether the catalog item is disabledfalse
updatedAtDateTime?When this catalog item was last updated"2026-03-24T17:26:46.983Z"

UpsertCatalogItemInput​

Only the fields you send are written. Omit a field to leave it unchanged.

NameTypeDescriptionExample
idID?Kojo id of an existing Catalog Item. When present, the row updates that item, and sku renames it"clktd7c1s0001ruj55b7gfuyh"
skustring?Your SKU. Required when id is absent; the row updates the item with this SKU, or creates one. Cannot be null or blank"PIPE-PVC-2IN"
descriptionstring?Primary description. Required to create an item. Cannot be null or blank"2 in. PVC Pipe, Schedule 40"
unitsOfMeasurestring?Unit of measure. Defaults to EA on create. Cannot be null or blank"FT"
manufacturerNamestring?Manufacturer name. null or blank clears it"Charlotte Pipe"
manufacturerPartNumberstring?Manufacturer Part Number (MPN). null or blank clears it"PVC 04020 0600"
universalProductCodestring?Universal Product Code (UPC). null or blank clears it"611942034555"

CatalogItemUpsertResult​

One result per input row, in input order.

NameTypeDescriptionExample
indexIntPosition of the row in inputs, starting at 00
skustring?The item's SKU after the write, or the row's SKU when it failed"PIPE-PVC-2IN"
idID?Kojo id of the Catalog Item. null when a new item could not be created"clktd7c1s0001ruj55b7gfuyh"
statusCatalogItemUpsertStatusWhat happened to the row"UPDATED"
disabledboolean?Whether the item is disabled. Upserts never change itfalse
errorCatalogItemUpsertError?Why the row failed. Present only when status is ERRORSee CatalogItemUpsertError

CatalogItemUpsertError​

NameTypeDescriptionExample
codestringMachine-readable reason. See the codes below; new codes may be added"DUPLICATE_SKU"
fieldstring?Input field the error refers to, when there is one"sku"
messagestringHuman-readable explanation"This SKU appears more than once in the request."
CodeMeaning
VALIDATION_ERRORA required field is null or blank, the row has neither id nor sku, or description is missing on create
DUPLICATE_SKUThe SKU appears in more than one row of the request; every such row fails
DUPLICATE_IDThe id appears in more than one row of the request, or two rows match the same item
NOT_FOUNDNo Catalog Item with this id exists in your catalog
SKU_ALREADY_EXISTSAnother Catalog Item already uses this SKU
PRODUCT_ALREADY_LINKEDThe UPC belongs to a product already linked to another Catalog Item
DUPLICATE_UPCTwo new rows in the request share a UPC
WRITE_FAILEDThe row could not be saved. Retry it

Enums​

CatalogItemUpsertStatus​

ValueDescription
CREATEDA new Catalog Item was created
UPDATEDAn existing Catalog Item was updated
UNCHANGEDThe row matched the stored Catalog Item, so nothing was written. Blank and null count as equal
ERRORThe row was not written; see error

REST Endpoints​

GET /catalog-items​

Read the organization's catalog items, ordered by updatedAt from oldest to newest.

Parameters​

This endpoint uses cursor pagination instead of the standard pagination parameters.

NameTypeDescription
limitInt?Maximum number of items per page. Defaults to and is capped at 500
cursorString?The nextCursor value from the previous page. Omit it to get the first page
filter.updatedAt_gteDateTime?Only return items updated at or after this time

A page can hold fewer items than limit, or none, while more pages remain. Keep requesting pages until nextCursor is null. An invalid cursor returns an error.

Response​

NameTypeDescription
countIntTotal number of matches for the filter
itemsCatalogItem[]The catalog items on this page
nextCursorString?Cursor for the next page, or null on the last page

Example Request​

GET https://api.kojo.tech/catalog-items?limit=100&filter.updatedAt_gte=2026-01-01T00:00:00.000Z

Example Response​

{
"count": 1,
"items": [
{
"id": "ckmnpybisiy5x08abky4g2d1f",
"sku": "EMT-075",
"description": "3/4\" EMT Conduit",
"nickname": "3/4 EMT",
"searchTerms": ["conduit", "EMT 3/4"],
"manufacturerName": "Allied Tube",
"manufacturerPartNumber": "101543",
"universalProductCode": "786564101543",
"unitsOfMeasure": "FT",
"disabled": false,
"updatedAt": "2026-03-24T17:26:46.983Z"
}
],
"nextCursor": null
}

GET /catalog-items/:idOrSku​

Read one catalog item by its Kojo id or your SKU. Use it to confirm a write landed: it reads the catalog directly rather than the search index that backs the list, so a write shows up almost immediately (if an item you just wrote returns not found, retry after a moment), and it returns disabled items with disabled: true. When no item in your organization matches, it returns 404. A SKU is matched exactly first, then ignoring case.

Parameters​

NameTypeDescription
idOrSkuStringThe catalog item's Kojo id, or your sku

Response​

A CatalogItem.

Example Request​

GET https://api.kojo.tech/catalog-items/EMT-075

Example Response​

{
"id": "ckmnpybisiy5x08abky4g2d1f",
"sku": "EMT-075",
"description": "3/4\" EMT Conduit",
"nickname": "3/4 EMT",
"searchTerms": ["conduit", "EMT 3/4"],
"manufacturerName": "Allied Tube",
"manufacturerPartNumber": "101543",
"universalProductCode": "786564101543",
"unitsOfMeasure": "FT",
"disabled": false,
"updatedAt": "2026-03-24T17:26:46.983Z"
}

POST /catalog-items/batch​

warning

This endpoint accepts at most 100 rows per request.

Creates or updates up to 100 Catalog Items. A row with id updates that item, and its sku renames it. A row without id updates the item with that sku, or creates a new item when no item has that SKU. A request with more than 100 rows is rejected as a whole. One failed row does not fail the others: check each row's status.

Parameters​

NameTypeDescription
inputsUpsertCatalogItemInput[]The rows to write

Response​

A list of CatalogItemUpsertResult, one per row.

Example Request​

POST https://api.kojo.tech/catalog-items/batch
{
"inputs": [
{ "sku": "PIPE-PVC-2IN", "description": "2 in. PVC Pipe, Schedule 40", "unitsOfMeasure": "FT" },
{ "id": "clktd7c1s0001ruj55b7gfuyh", "sku": "PIPE-PVC-3IN", "manufacturerName": null },
{ "sku": "PIPE-PVC-4IN", "description": null }
]
}

Example Response​

[
{ "index": 0, "sku": "PIPE-PVC-2IN", "id": "clm0b2x4y0000abcd1234efgh", "status": "CREATED", "disabled": false, "error": null },
{ "index": 1, "sku": "PIPE-PVC-3IN", "id": "clktd7c1s0001ruj55b7gfuyh", "status": "UPDATED", "disabled": false, "error": null },
{
"index": 2,
"sku": "PIPE-PVC-4IN",
"id": null,
"status": "ERROR",
"disabled": null,
"error": { "code": "VALIDATION_ERROR", "field": "description", "message": "description cannot be null or blank." }
}
]