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​
| Name | Type | Description | Example |
|---|---|---|---|
| id | ID | Unique identifier for the catalog item | "ckmnpybisiy5x08abky4g2d1f" |
| sku | String? | Your organization's unique SKU for the catalog item | "EMT-075" |
| description | String? | Description of the catalog item | "3/4\" EMT Conduit" |
| nickname | String? | The name your organization gave the catalog item | "3/4 EMT" |
| searchTerms | String[] | Your organization's search terms for the catalog item | ["conduit", "EMT 3/4"] |
| manufacturerName | String? | Name of the manufacturer | "Allied Tube" |
| manufacturerPartNumber | String? | The manufacturer part number | "101543" |
| universalProductCode | String? | The universal product code | "786564101543" |
| unitsOfMeasure | String? | The unit of measure for the catalog item | "FT" |
| disabled | Boolean | Whether the catalog item is disabled | false |
| updatedAt | DateTime? | 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.
| Name | Type | Description | Example |
|---|---|---|---|
| id | ID? | Kojo id of an existing Catalog Item. When present, the row updates that item, and sku renames it | "clktd7c1s0001ruj55b7gfuyh" |
| sku | string? | 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" |
| description | string? | Primary description. Required to create an item. Cannot be null or blank | "2 in. PVC Pipe, Schedule 40" |
| unitsOfMeasure | string? | Unit of measure. Defaults to EA on create. Cannot be null or blank | "FT" |
| manufacturerName | string? | Manufacturer name. null or blank clears it | "Charlotte Pipe" |
| manufacturerPartNumber | string? | Manufacturer Part Number (MPN). null or blank clears it | "PVC 04020 0600" |
| universalProductCode | string? | Universal Product Code (UPC). null or blank clears it | "611942034555" |
CatalogItemUpsertResult​
One result per input row, in input order.
| Name | Type | Description | Example |
|---|---|---|---|
| index | Int | Position of the row in inputs, starting at 0 | 0 |
| sku | string? | The item's SKU after the write, or the row's SKU when it failed | "PIPE-PVC-2IN" |
| id | ID? | Kojo id of the Catalog Item. null when a new item could not be created | "clktd7c1s0001ruj55b7gfuyh" |
| status | CatalogItemUpsertStatus | What happened to the row | "UPDATED" |
| disabled | boolean? | Whether the item is disabled. Upserts never change it | false |
| error | CatalogItemUpsertError? | Why the row failed. Present only when status is ERROR | See CatalogItemUpsertError |
CatalogItemUpsertError​
| Name | Type | Description | Example |
|---|---|---|---|
| code | string | Machine-readable reason. See the codes below; new codes may be added | "DUPLICATE_SKU" |
| field | string? | Input field the error refers to, when there is one | "sku" |
| message | string | Human-readable explanation | "This SKU appears more than once in the request." |
| Code | Meaning |
|---|---|
| VALIDATION_ERROR | A required field is null or blank, the row has neither id nor sku, or description is missing on create |
| DUPLICATE_SKU | The SKU appears in more than one row of the request; every such row fails |
| DUPLICATE_ID | The id appears in more than one row of the request, or two rows match the same item |
| NOT_FOUND | No Catalog Item with this id exists in your catalog |
| SKU_ALREADY_EXISTS | Another Catalog Item already uses this SKU |
| PRODUCT_ALREADY_LINKED | The UPC belongs to a product already linked to another Catalog Item |
| DUPLICATE_UPC | Two new rows in the request share a UPC |
| WRITE_FAILED | The row could not be saved. Retry it |
Enums​
CatalogItemUpsertStatus​
| Value | Description |
|---|---|
| CREATED | A new Catalog Item was created |
| UPDATED | An existing Catalog Item was updated |
| UNCHANGED | The row matched the stored Catalog Item, so nothing was written. Blank and null count as equal |
| ERROR | The 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.
| Name | Type | Description |
|---|---|---|
| limit | Int? | Maximum number of items per page. Defaults to and is capped at 500 |
| cursor | String? | The nextCursor value from the previous page. Omit it to get the first page |
| filter.updatedAt_gte | DateTime? | 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​
| Name | Type | Description |
|---|---|---|
| count | Int | Total number of matches for the filter |
| items | CatalogItem[] | The catalog items on this page |
| nextCursor | String? | 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​
| Name | Type | Description |
|---|---|---|
| idOrSku | String | The 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​
| Name | Type | Description |
|---|---|---|
| inputs | UpsertCatalogItemInput[] | 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." }
}
]