Understanding products and categories

Propeller's catalog is built around two core types: products and clusters. A product is the standalone, purchasable unit. A cluster groups multiple products together as variants of the same item. Both live inside a category tree and can carry cross-sell and upsell relations, pricing, inventory, attributes and media.

Products

A product (class: PRODUCT) is the fundamental unit in Propeller. Every item that can be ordered, priced and stocked is a product. Products are identified by their productId.

Core fields

Each product carries identification and descriptive fields:

Field	Description
sku	Stock keeping unit code
eanCode	European Article Number
barCode	Barcode
names	Product name, localized per language
shortNames	Abbreviated name, used in compact displays like order lines
descriptions	Full description (localized, supports HTML)
shortDescriptions	Short description (localized, supports HTML)
manufacturer	Manufacturer name
manufacturerCode	Manufacturer's own product code
supplier	Supplier name
supplierCode	Supplier's own product code

Ordering and packaging

Products define how they can be ordered and how they are packaged:

Field	Description
unit	The base unit in which the product is ordered
minimumQuantity	Minimum order quantity
economicOrderQuantity	The quantity that provides the best value
purchaseUnit	Unit for purchase orders
purchaseMinimumQuantity	Minimum quantity for purchase orders
package	Package type (e.g. BOX)
packageUnit	What one item in the package looks like (e.g. PC)
packageUnitQuantity	Number of items per package

Status

Every product has a status that controls its availability:

Status	Meaning
A	Available
N	Not available
P	Phase out
S	Presale
R	Restricted
T	Out of stock

Additional flags control visibility and behavior: hidden (Y/N), orderable (Y/N) and physical (Y/N, indicating whether it is a physical product or something like a service or warranty).

Standalone vs. cluster products

A product can exist on its own (standalone) or as a variant inside a cluster. The containerClass field tells you which situation applies:

• CATEGORY means the product lives standalone in a category.
• CLUSTER means the product belongs to a cluster. You can navigate to its parent cluster via the cluster field.

SEO metadata

Products carry localized SEO fields: metadataTitles, metadataDescriptions, metadataKeywords and metadataCanonicalUrls.

Clusters

A cluster (class: CLUSTER) groups multiple products together as variants of the same item. Clusters are identified by their clusterId. Where a product is what gets ordered, a cluster is the presentation layer that ties variants together on a single product page.

Cluster-level vs. product-level data

Clusters have their own names, descriptions and shortDescriptions. These are shared presentation data that apply to all variants. Each product inside the cluster carries its own variant-specific data: its own sku, names, pricing, inventory and attribute values.

Cluster configuration

Every cluster has a config (ClusterConfig) that defines which attributes differentiate its variants. The config contains settings, each specifying:

Setting field	Description
name	The attribute name that varies across products (e.g. AFMETING_MM, KLEURTEMPERATUUR)
displayType	How the selector should render: DROPDOWN, RADIO, IMAGE or COLOR
priority	Display order (0 is first)

For example, an LED panel cluster uses config settings AFMETING_MM (priority 0) and KLEURTEMPERATUUR (priority 1). Each product in the cluster then has specific values for these attributes:

Cluster: "LED Paneel Backlit"
├── LED Paneel Backlit 60x60 3000K   (AFMETING_MM: 60 x 60 cm, KLEURTEMPERATUUR: 3000K)
├── LED Paneel Backlit 60x60 4000K   (AFMETING_MM: 60 x 60 cm, KLEURTEMPERATUUR: 4000K)
├── LED Paneel Backlit 60x60 6000K   (AFMETING_MM: 60 x 60 cm, KLEURTEMPERATUUR: 6000K)
├── LED Paneel Backlit 30x120 3000K  (AFMETING_MM: 30 x 120 cm, KLEURTEMPERATUUR: 3000K)
├── LED Paneel Backlit 30x120 4000K  (AFMETING_MM: 30 x 120 cm, KLEURTEMPERATUUR: 4000K)
└── ...

Default product

Every cluster has a defaultProduct. This is the variant that should be shown when no specific selection has been made, for example on listing pages where you need a representative price and image.

Cluster options

Clusters can have options, which are add-on product groups. Options are not variants. They represent additional items a customer can select alongside the main product, such as accessories or service add-ons.

Each option has its own names, descriptions, an isRequired flag (Y/N) and a list of products to choose from. An option can also have a defaultProduct.

For example, the LED panel cluster has two options:

• Opbouwframe (optional): mounting frames in different sizes, 3 products to choose from.
• Noodverlichting module (optional): emergency lighting modules, 2 products to choose from.

Categories

Products and clusters are organized into categories. Categories form a tree structure where each category has a parent (except root categories) and can have child categories.

Each product and cluster belongs to one primary category via categoryId. The categoryPath field returns the full hierarchy from root to the assigned category, which is useful for building breadcrumbs. Products can also be linked to additional categories, allowing them to appear in multiple places in the catalogue structure without duplication.

Example from a real catalog:

PDM (root)
├── Bureaustoelen
│   ├── EM bureaustoelen
│   ├── Interstuhl bureaustoelen
│   └── ...
├── Elektrotechnisch & Industrieel Installatiemateriaal
│   ├── LED verlichting
│   └── ...
└── ...

For practical details on querying and navigating categories, see Categories and navigation.

Cross-sell and upsell relations

Products and clusters can have cross-sell and upsell relations via crossupsellsFrom. Each relation has a type and an optional subType:

Type	Purpose
ACCESSORIES	Complementary items (e.g. a floor mat for a desk chair)
ALTERNATIVES	Substitute products (e.g. a different brand of chair)
RELATED	Related items from the same category or brand
PARTS	Component parts of the product
OPTIONS	Optional add-ons

Each relation points to either a productTo (a standalone product) or a clusterTo (a cluster), never both. This means cross-sell targets can be individual products or entire product groups with variants.

For example, a desk chair product might have:

• ACCESSORIES: four different floor mats (all pointing to standalone products).
• ALTERNATIVES: chairs from other brands, including one relation pointing to a cluster with its own variants.
• RELATED: other chairs from the same manufacturer.

How this relates to pricing

Pricing lives on products, not on clusters. Each product has a priceData field with the base price configuration:

Field	Description
list	The default sales price
store	The in-store price (can differ from the list price)
suggested	Manufacturer's recommended retail price
per	The quantity the listed price applies to
defaultTaxCode	Tax code: H (high), L (low) or N (none)
bulkPriceDiscountType	How bulk discounts are applied: as a net price or as a percentage

On top of the base price, products can have bulk prices (tiered pricing based on quantityFrom) and cost prices (purchase prices, also with quantityFrom).

When requesting prices for a specific customer context, use the price field which returns calculated prices including net, gross and any applicable discounts.

For the full pricing model, see Understanding pricing layers.

How this relates to inventory

Inventory lives on products. The inventory field provides:

• totalQuantity: the aggregate stock across all warehouses.
• localQuantity: stock in local (own) warehouses.
• supplierQuantity: stock held by suppliers.
• nextDeliveryDate: the earliest expected restocking date.
• balance[]: a per-warehouse breakdown, where each entry includes quantity, warehouseId, supplier and nextDeliveryDate.

A single product can have stock spread across multiple warehouses and multiple suppliers.

How this relates to attributes

Attributes are key-value pairs attached to products. Each attribute is defined by an attributeDescription that specifies the attribute's name, type, group and behavior flags (isSearchable, isPublic, isSystem, isHidden).

Supported attribute types: TEXT, ENUM, COLOR, DATETIME, INT and DECIMAL.

Attributes are organized into groups (e.g. "Kantoormeubilair", "LED verlichting") and can be localized with descriptions and units per language.

In clusters, attributes play a special role: the cluster's config settings reference specific attributes (by name) as the properties that differentiate variants. The attribute values on each product within the cluster then determine which variant is which.

How this relates to media

Media is attached to products via the media field, which contains three paginated sub-fields:

• images: product photos with imageVariants (named sizes like small, medium), alt text, description and priority for ordering.
• videos: product videos.
• documents: downloadable files like PDFs and technical sheets.

Images are served with transformation parameters for resizing and cropping, so you can request the appropriate size for thumbnails, listing pages or detail views.

For practical details, see Media and assets.

How this relates to bundles

Products can be part of bundles. A bundle groups multiple products together and sells them at a combined price, typically with a discount compared to buying each item individually.

Each bundle has:

Field	Description
id	Unique bundle identifier
name	Bundle name
discount	Discount applied to the bundle
condition	Rules for when the bundle applies
price	Combined bundle price (gross, net, original prices)
items	The products included in the bundle

One product in a bundle is the leader (marked with isLeader). The leader is the main product that the bundle is displayed on. The other items are complementary products included in the bundle offer.

Bundles are returned as a list on the product via the bundles field. For adding bundles to a cart, see Cart management.