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

DELETE /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/456e7890-e89b-12d3-a456-426614174001
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.