In any e-commerce application, the product, product variant and category are core entities that define many features of a Web site. This article describes the product-related design of http://dev.commercetools.com/.
A product category can have only one parent category. A product can be in multiple categories. The complexity of a product design lies in three areas: attributes, custom attributes and product variants. Futhermore, it is nice to be able to create product bundles to sell products closely related to each other.
A product belongs to one
ProductType that defines a set of attributes for the product.
A product has one master variant. Optionally, a product can have multiple variants. All product variants have the same set of attributes defined by the product’s
ProductType. Each variant may have different attribute value in if an attribute’s
attributeConstraint is not
Categories form a simple tree structure because a category can only have one parent category. Each category have an
ancestors field that is an arrary of references of all ancestor categories toward a root category.
A product type defines a
name and a set of
attributes. Because the
attributes field is an array of product attributes, attributes can be changed, added or removed.
A product attribute is defined by an
AttributeDefinition class. The following are some important fields:
AttributeTypevalue. All attribute types have a
- Some attribute types (
datetime) only have a
- Other attritube types have additional fields.
lenumtypes have a
valuesfield. An enum value has a
labelis a localized string in
settype has an
elementTypefield that is another
nestedtype has a
typeReferencefield that references a
referencetype has a
referenceTypeIdfield that is the name of the resource type (such as “product”, “product-type”, “channel”, “state” etc.) that the value should reference.
referencetype can be used to create product bundles.
- Some attribute types (
name: a unique name string in this product type. *
isRequired: a boolean value specifies whether the attribute is a mandatory one.
attributeConstraint: one of the
None: no constraint.
Unique: an attribute value should be different in each variant.
CombinationUnique: a set of attributes that have this contraint should have different combinations in each variant.
SameForAll: value should be the same in all variant.
isSearchable: whether the attribute value is enabled in product search.
Because all product variants share the same set of attributes, it is important to understand the ``attributeConstraint
field. This field determines the attribute value in each variant. Most attributes should have a value of SameForAll
because all variants share the same attribute value as the master variant. When the constriant is None
or CombinationUnique`, each variant should set the value for this attribute and agree with the contstaint.
A product belongs to only one
productType as described above. Other important fields are:
key: a user-specific unique id for the product. Can be used in search.
taxCategory: refrence to a
state: refrence to a
Statethat might be useful for workflow state management.
reviewRatingStatistics: review statistics.
ProductCatalogData is used to manage catalog publish and states. It has four fields:
publish: whether the product is published or not.
current: the current product data of type
staged: the staged product data.
hasStagedChanges: whether the staged data is different from the current data.
It supports the following operations:
- Pulibsh: When publish a product, the staged product data becomes the current data, the
publishedis true and
- Unpbulish: When unpublish a product, the
- Revert Staged: when revert staged, the staged data is reseet to the current data.
- Update actions: When update a product and the
false, both the current and staged data are changed for the update action. If the
true, only staged data is changed.
This is the real product data excluding tax, state and review. It has the following fields:
name: a localized string.
categories: an array of refrence to a category.
categoryOrderHints: a JSON object of categroy id and hints (a value between 0 and 1 where 1 is the highest) used to control the order of products appeared in a category.
description: a localized string.
slug: a localized string.
metaKeywords: used for SEO.
masterVariant: the master product variant. Only mater variant can change attributes with a
variants: an array of varaints.
searchKeywords: a json object that is an array of
SearchKeywordfor each langugages. A
SearchKeywordhas a text and a suggested tokenizer.
This represents a concrete product instance that usually has a unique SKU, some special attribute values, images, assets, prices and individual inventory. Important fields are:
id: a sequential number of the variant within the product.
sku: the variant sku.
key: a user specific unique identifier for the variant.
prices: an array of price for different currency, customer, channle, country etc.
prices: an array of price.
attributes: an array of attribute values in the form of
images: an array of
assets: an array of
ProductVariantAvilabilityvalue for inventory.