ForSURE.categorylist.models.items.endpoints

GET /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items?offset=0&limit=50&country=NL&search=product
async def list_items()

List items for a revision with pagination and filtering.

This endpoint retrieves a paginated list of items from a revision with support for filtering, searching, and sorting. Items can be filtered by various criteria including column names, country, report type, status, and more.

Parameters

revision_uuid UUID - UUID of the revision to list items from.

offset int, default 0 - Number of items to skip for pagination.

limit int, optional - Maximum number of items to return.

column_names list[str], optional - Filter by specific column names to include.

country str, optional - Filter items by country code.

isGeneralPackaging bool, optional - Filter to show only general packaging columns.

report_type str, optional - Filter by report type.

pro str, optional - Filter by pro identifier.

search str, optional - Free text search term to filter items.

status ItemStatus, optional - Filter by item status (PENDING, APPROVED, etc.).

filters str, optional - Additional filter criteria as JSON string.

order_by str, optional - Column name to sort by.

order_direction str, optional - Sort direction: "asc" or "desc".

Returns

PaginatedResponse[ItemResponse]

Paginated response containing:

items list[ItemResponse] - List of items matching the filters
total int - Total number of items matching the filters
next_offset int, optional - Offset for next page
prev_offset int, optional - Offset for previous page

Example

curl -X GET "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items?offset=0&limit=50&country=NL&search=product" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "items": [
    {
      "uuid": "456e7890-e89b-12d3-a456-426614174001",
      "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "sku": "SKU123",
      "data": {"general:SKU": "SKU123", "general:Product Name": "Product"},
      "status": "PENDING"
    }
  ],
  "total": 100,
  "next_offset": 50,
  "prev_offset": null
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to list items"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Column filtering is based on label types (GENERAL, COUNTRY, etc.) and the specified filters.

POST /saas/categorylist/items
async def create_item()

Create a new item in a revision.

This endpoint creates a new item with the specified SKU and data in a revision. The data parameter should be a JSON string containing the item's column values.

Parameters

revision_uuid UUID - UUID of the revision to create the item in.

sku str - Stock Keeping Unit identifier for the item.

data str, optional - JSON string containing item data (column values).

Returns

ItemResponse

Response containing:

uuid UUID - Item UUID
revision_uuid UUID - Revision UUID
sku str - Item SKU
data dict - Item data (column values)
status ItemStatus, optional - Item status
created_at str, optional - Creation timestamp
created_by str, optional - Creator username
updated_at str, optional - Last update timestamp
updated_by str, optional - Last updater username

Example

curl -X POST "https://api.example.com/saas/categorylist/items" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "revision_uuid=123e4567-e89b-12d3-a456-426614174000" \
-F "sku=SKU123" \
-F 'data={"general:Product Name": "Product"}'

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "uuid": "456e7890-e89b-12d3-a456-426614174001",
  "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "sku": "SKU123",
  "data": {"general:SKU": "SKU123", "general:Product Name": "Product"},
  "status": "PENDING"
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to create item"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Data must be valid JSON if provided.

POST /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/create
async def create_empty_item()

Create a new empty item in a revision.

This endpoint creates a new item with no SKU and empty data in a revision. Useful for creating placeholder items that will be filled in later.

Parameters

revision_uuid UUID - UUID of the revision to create the item in.

Returns

ItemResponse

Response containing:

uuid UUID - Item UUID
revision_uuid UUID - Revision UUID
sku str, optional - Item SKU (null for empty items)
data dict - Item data (empty initially)
status ItemStatus, optional - Item status
created_at str, optional - Creation timestamp
created_by str, optional - Creator username
updated_at str, optional - Last update timestamp
updated_by str, optional - Last updater username

Example

curl -X POST "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/create" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "uuid": "456e7890-e89b-12d3-a456-426614174001",
  "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "sku": null,
  "data": {},
  "status": "PENDING"
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to create item"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Creates an item with no SKU and empty data.

PUT /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items/456e7890-e89b-12d3-a456-426614174001
async def update_item()

Update an item's data or status.

This endpoint updates an item's data (column values) and/or status. The data parameter should be a JSON string containing the updated column values.

Parameters

item_uuid UUID - UUID of the item to update.

revision_uuid UUID - UUID of the revision containing the item.

data str, optional - JSON string containing updated item data (column values).

status str, optional - New status for the item (PENDING, APPROVED, etc.).

Returns

ItemResponse

Response containing:

uuid UUID - Item UUID
revision_uuid UUID - Revision UUID
sku str - Item SKU
data dict - Updated item data
status ItemStatus, optional - Updated item status
created_at str, optional - Creation timestamp
created_by str, optional - Creator username
updated_at str, optional - Last update timestamp
updated_by str, optional - Last updater username

Example

curl -X PUT "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items/456e7890-e89b-12d3-a456-426614174001" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F 'data={"general:Product Name": "Updated Product"}' \
-F "status=APPROVED"

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "uuid": "456e7890-e89b-12d3-a456-426614174001",
  "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "sku": "SKU123",
  "data": {"general:SKU": "SKU123", "general:Product Name": "Updated Product"},
  "status": "APPROVED"
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to update item"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Data must be valid JSON if provided. Status must be a valid ItemStatus enum value.

PUT /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items/456e7890-e89b-12d3-a456-426614174001/column
async def update_item_column()

Update an item's column value.

This endpoint updates a single column value for an item. If the item exists in a base revision, a new draft item is created in the current revision.

Parameters

item_uuid UUID - UUID of the item to update.

revision_uuid UUID - UUID of the revision containing the item.

column str - Column name (internal name) to update.

value str, default "" - New value for the column.

Returns

ItemResponse

Response containing:

reload bool - Whether client should reload (true if new draft was created)
uuid UUID - Item UUID
revision_uuid UUID - Revision UUID
sku str - Item SKU
data dict - Updated item data
status ItemStatus, optional - Item status
created_at str, optional - Creation timestamp
created_by str, optional - Creator username
updated_at str, optional - Last update timestamp
updated_by str, optional - Last updater username

Example

curl -X PUT "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items/456e7890-e89b-12d3-a456-426614174001/column" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "column=general:Product Name" \
-F "value=New Product Name"

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "reload": false,
  "uuid": "456e7890-e89b-12d3-a456-426614174001",
  "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "sku": "SKU123",
  "data": {"general:SKU": "SKU123", "general:Product Name": "New Product Name"}
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to update item"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. If item is in base revision, a new draft item is created in the current revision.

DELETE /saas/categorylist/items/456e7890-e89b-12d3-a456-426614174001
async def delete_item()

Soft delete an item by setting its status to DELETED.

This endpoint performs a soft delete on an item by setting its status to DELETED. The item is not permanently removed from the database.

Parameters

item_uuid UUID - UUID of the item to delete.

Returns

dict

Response containing:

success bool - True if item was deleted successfully
uuid str - UUID of the deleted item

Example

curl -X DELETE "https://api.example.com/saas/categorylist/items/456e7890-e89b-12d3-a456-426614174001" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "success": true,
  "uuid": "456e7890-e89b-12d3-a456-426614174001"
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to delete item"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. This is a soft delete - the item status is set to DELETED or ARCHIVED, not permanently removed.

PUT /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items/sku/SKU123
async def update_item_by_sku()

Update an item by revision UUID and SKU.

This endpoint updates an item identified by its SKU within a revision. The data and status can be updated via JSON body.

Parameters

revision_uuid UUID - UUID of the revision containing the item.

sku str - SKU of the item to update.

data dict, optional - Dictionary containing updated item data (column values).

status ItemStatus, optional - New status for the item.

Returns

ItemResponse

Response containing:

uuid UUID - Item UUID
revision_uuid UUID - Revision UUID
sku str - Item SKU
data dict - Updated item data
status ItemStatus, optional - Updated item status
created_at str, optional - Creation timestamp
created_by str, optional - Creator username
updated_at str, optional - Last update timestamp
updated_by str, optional - Last updater username

Example

curl -X PUT "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items/sku/SKU123" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "data": {"general:Product Name": "Updated Product"},
  "status": "APPROVED"
}'

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "uuid": "456e7890-e89b-12d3-a456-426614174001",
  "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "sku": "SKU123",
  "data": {"general:SKU": "SKU123", "general:Product Name": "Updated Product"},
  "status": "APPROVED"
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to update item by SKU"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Item must exist in the specified revision.

DELETE /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items/sku/SKU123
async def delete_item_by_sku()

Soft delete an item by revision UUID and SKU.

This endpoint performs a soft delete on an item identified by its SKU within a revision. The item is not permanently removed from the database, but its status is set to DELETED.

Parameters

revision_uuid UUID - UUID of the revision containing the item.

sku str - Stock Keeping Unit identifier of the item to delete.

Returns

dict

Response containing:

success bool - True if item was deleted successfully
revision_uuid str - UUID of the revision
sku str - SKU of the deleted item

Example

curl -X DELETE "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/items/sku/SKU123" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "success": true,
  "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "sku": "SKU123"
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to delete item by SKU"
}

Or if the item is not found:

{
  "detail": "Item with SKU SKU123 in revision 123e4567-e89b-12d3-a456-426614174000 not found or not accessible"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. This is a soft delete - the item status is set to DELETED, not permanently removed. The SKU must exist in the specified revision.

PUT /saas/categorylist/items/sku/archive
async def archive_items_by_sku()

Archive one or more items by SKU on the latest draft revision for the caller's organization.

This endpoint always operates on the latest draft revision for the organization's most recent categorylist version (a draft is created from the latest published revision if one doesn't already exist), so the caller does not need to know or pass a version/revision UUID. SKUs are passed in the JSON body so they can safely contain any characters (e.g. ., -, /). Each SKU's status is set to ARCHIVED. Processing is best-effort: SKUs that aren't found in the latest draft are skipped and listed under not_found rather than failing the whole request.

Parameters

skus list[str] - SKUs of the items to archive (JSON body field, 1-500 SKUs).

Returns

BulkSkuActionResponse

updated list[ItemResponse] - Items successfully archived.
not_found list[str] - SKUs that were not found and were skipped.

Example

curl -X PUT "https://api.example.com/saas/categorylist/items/sku/archive" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"skus": ["SKU/123.A", "SKU-456"]}'

Response Example

Successful response

{
  "updated": [
    {
      "uuid": "456e7890-e89b-12d3-a456-426614174001",
      "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "sku": "SKU/123.A",
      "data": {"general:SKU": "SKU/123.A"},
      "status": "ARCHIVED"
    }
  ],
  "not_found": ["SKU-456"]
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. This is a soft delete - item status is set to ARCHIVED, not permanently removed. Archived items are excluded from the active catalog and are preserved as-is across publishes, so they can easily be unarchived later.

PUT /saas/categorylist/items/sku/unarchive
async def unarchive_items_by_sku()

Unarchive one or more items by SKU on the latest draft revision for the caller's organization.

This endpoint always operates on the latest draft revision for the organization's most recent categorylist version (a draft is created from the latest published revision if one doesn't already exist), so the caller does not need to know or pass a version/revision UUID. SKUs are passed in the JSON body so they can safely contain any characters (e.g. ., -, /). Only items currently ARCHIVED are affected; their status is reset to PENDING. Processing is best-effort: SKUs that aren't found in the latest draft, or that are found but not currently ARCHIVED, are skipped and listed under not_found rather than failing the whole request.

Parameters

skus list[str] - SKUs of the items to unarchive (JSON body field, 1-500 SKUs).

Returns

BulkSkuActionResponse

updated list[ItemResponse] - Items successfully unarchived.
not_found list[str] - SKUs that were skipped (not found, or not currently archived).

Example

curl -X PUT "https://api.example.com/saas/categorylist/items/sku/unarchive" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"skus": ["SKU/123.A", "SKU-456"]}'

Response Example

Successful response

{
  "updated": [
    {
      "uuid": "456e7890-e89b-12d3-a456-426614174001",
      "revision_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "sku": "SKU/123.A",
      "data": {"general:SKU": "SKU/123.A"},
      "status": "PENDING"
    }
  ],
  "not_found": ["SKU-456"]
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission.

POST /saas/categorylist/items/sku/archived
async def check_archived_status_by_sku()

Check whether one or more SKUs are archived on the latest draft revision for the caller's organization.

This is a read-only counterpart to the archive/unarchive endpoints: it resolves the same latest draft revision (a draft is created from the latest published revision if one doesn't already exist), and for each requested SKU reports whether it is currently ARCHIVED, found but not archived, or not found at all. SKUs are passed in the JSON body so they can safely contain any characters (e.g. ., -, /).

Parameters

skus list[str] - SKUs to check (JSON body field, 1-500 SKUs).

Returns

SkuArchiveStatusResponse

archived list[str] - SKUs found and currently ARCHIVED.
not_archived list[str] - SKUs found but not currently ARCHIVED.
not_found list[str] - SKUs not found in the latest draft.

Example

curl -X POST "https://api.example.com/saas/categorylist/items/sku/archived" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"skus": ["SKU/123.A", "SKU-456"]}'

Response Example

Successful response

{
  "archived": ["SKU/123.A"],
  "not_archived": ["SKU-456"],
  "not_found": ["SKU-789"]
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Read-only: no item is modified by this endpoint.

async def delete_item_by_uuid()

Soft delete an item by revision UUID and item UUID.

This endpoint performs a soft delete on an item identified by its UUID within a revision. The item is not permanently removed from the database.

Parameters

revision_uuid UUID - UUID of the revision containing the item.

item_uuid UUID - UUID of the item to delete.

Returns

dict

Response containing:

success bool - True if item was deleted successfully
uuid str - UUID of the deleted item

Example

curl -X DELETE "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/456e7890-e89b-12d3-a456-426614174001" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response

If the request was successful you should receive the status code 200 and a response body like this:

{
  "success": true,
  "uuid": "456e7890-e89b-12d3-a456-426614174001"
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to delete item"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. This is a soft delete - the item status is set to DELETED, not permanently removed.

GET /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/filter-options?column=general%3ACategory
async def get_filter_options()

Get filter options for a specific column in a revision.

This endpoint retrieves all unique values for a specified column across all items in the revision and base revision (if applicable). The response type is automatically determined based on the column values: numeric columns return min/max ranges, while text/multi-value columns return a list of available values.

Parameters

revision_uuid UUID - UUID of the revision to get filter options for.

column str - Internal name of the column to get filter options for (e.g., "general:SKU", "general:Product Name").

Returns

dict

Response containing filter options. The structure depends on the column type:

For numeric columns:

type str - "numeric"
min float - Minimum value in the column
max float - Maximum value in the column

For multi-value columns (multiple distinct values):

type str - "multi"
values list - Sorted list of unique values

For text columns (single or few values):

type str - "text"
values list - Sorted list of unique values

Example

curl -X GET "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/filter-options?column=general%3ACategory" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response (multi-value column)

If the request was successful you should receive the status code 200 and a response body like this:

{
  "type": "multi",
  "values": ["Electronics", "Clothing", "Home & Garden", "Sports"]
}

Successful response (numeric column)

For numeric columns, the response will look like this:

{
  "type": "numeric",
  "min": 10.99,
  "max": 999.99
}

Successful response (text column)

For text columns with few values:

{
  "type": "text",
  "values": ["Active", "Inactive"]
}

Error response

If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to get filter options"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. The column name should be URL-encoded (e.g., "general:Category" becomes "general%3ACategory"). Values are retrieved from both the revision and its base revision, with revision values taking precedence. Only non-deleted and non-archived items are considered.