Overview

The Catalog Products API allows you to create, retrieve, update, and delete products within a catalog. Understand how products are structured and validated before using the APIs.

Refer to the following endpoints:

• Create Single Product API
• Create Products (Bulk) API
• List Products API
• Get Single Product API
• Update Single Product API
• Update Products (Bulk) API
• Delete Single Product API
• Delete Products (Bulk) API

Product Model

A product consists of the following attributes:

• identity (required), unique identifier for the product
• name (required), display name
• imageUrl (required), publicly accessible image URL
• customAttributes (optional), key-value map defined by the catalog schema

Example

{
  "identity": "PROD-001",
  "name": "Running Shoes",
  "imageUrl": "https://example.com/images/shoes.png",
  "customAttributes": {
    "brand": "Nike",
    "price": 99.99,
    "category": "Shoes",
    "in_stock": true
  }
}

Fixed Fields and Custom Attributes

• Fixed fields (identity, name, imageUrl) are always required
• Custom attributes are defined in the catalog schema and validated during write operations
• Attributes can be marked as filterable for querying

Validation

When creating or updating products:

• Required fields must be present
• Custom attributes must match schema data types
• Invalid products may fail individually in bulk requests

Querying Products

Listing products supports:

• Pagination (page, size)

• Sorting (sortBy, sortOrder)

  Search text can be used to match products by name and identity.

Bulk Operations

All product APIs support bulk operations.

• Maximum 100 products per request
• Maximum payload size 500 KB

File Upload vs Products API

• Use Signed URL upload for bulk ingestion
• Use Products API for incremental or real-time updates

Best Practices

• Use stable product identifiers
• Mark only necessary attributes as filterable
• Keep batch sizes small
• Track and retry failed records