Products
Products are the sellable goods in an e-commerce project on the commercetools platform.
Products contain ProductVariants, which represent a single sellable product (often an individual SKU). Mapping your goods to commercetools products and variants efficiently is an important part of working with the platform. For more information, see the Product Modeling Guide.
Representations
Product
The full representation of a product combines the current and staged representations in a single representation.
id
- String
The unique ID of the product.key
- String - Optional
User-specific unique identifier for the product. Product keys are different from product variant keys.version
- Number
The current version of the product.createdAt
- DateTimecreatedBy
- CreatedBy BETA
Present on resources created after 2019-02-01 except for events not tracked.lastModifiedAt
- DateTimelastModifiedBy
- LastModifiedBy BETA
Present on resources updated after 2019-02-01 except for events not tracked.productType
- Reference to a ProductTypemasterData
- ProductCatalogData
The product data in the master catalog.taxCategory
- Reference to a TaxCategory - Optionalstate
- Reference to a State - OptionalreviewRatingStatistics
- ReviewRatingStatistics - Optional
Statistics about the review ratings taken into account for this product.
ProductCatalogData
published
- Boolean
Whether the product is published.current
- ProductData
The current data of the product.staged
- ProductData
The staged data of the product.hasStagedChanges
- Boolean
Whether the staged data is different from the current data.
ProductData
name
- LocalizedStringcategories
- Array of Reference to a Category
References to categories the product is in.categoryOrderHints
- CategoryOrderHints - Optionaldescription
- LocalizedString - Optionalslug
- LocalizedString
Human-readable identifiers usually used as deep-link URL to the related product. Each slug is unique across a project, but a product can have the same slug for different languages.
For good performance, indexes are provided for the first 15languages
set on the Project.metaTitle
- LocalizedString - OptionalmetaDescription
- LocalizedString - OptionalmetaKeywords
- LocalizedString - OptionalmasterVariant
- ProductVariantvariants
- Array of ProductVariantsearchKeywords
- SearchKeywords
ProductVariant
id
- Number
The sequential ID of the variant within the product.sku
- String - Optional
The unique SKU of the variant.key
- String - Optional
User-specific unique identifier for the variant. Product variant keys are different from product keys.prices
- Array of Price - Optional
The prices of the variant. The prices does not contain two prices for the same price scope (same currency, country, customer group and channel).attributes
- Array of Attribute - Optionalprice
- Price - Optional
Only appears when price selection is used. This field cannot be used in a query predicate.images
- Array of Image - Optionalassets
- Array of Asset - Optionalavailability
- ProductVariantAvailability - Optional
The availability is set if the variant is tracked by the inventory. The field might not contain the latest inventory state (it is eventually consistent) and can be used as an optimization to reduce calls to the inventory service.isMatchingVariant
- Boolean - Optional
Only appears in response to a Product Projection Search request to mark this variant as one that matches the search query.scopedPrice
- ScopedPrice - Optional
Only appears in response to a Product Projection Search with price selection. Can be used to sort, filter and facet.scopedPriceDiscounted
- Boolean - Optional
Only appears in response to a Product Projection Search request when price selection is used.
ProductVariantAvailability
isOnStock
- Boolean - OptionalrestockableInDays
- Number - Optional
The number of days it takes to restock a product once it is out of stock.availableQuantity
- Number - Optional
The number of items of this product variant that are currently available in stockisOnStock
,restockableInDays
andquantityOnStock
are based on the Inventory Entry with no supply channel for this variant.channels
- Map of ProductVariantAvailability per Channelid
- Optional
For each Inventory Entries with a supply channel, an entry is added intochannels
:- the key is the Channel
id
- the value is an object containing the data
isOnStock
,restockableInDays
andavailableQuantity
for the Inventory Entry with the supply channel for this variant.
- the key is the Channel
Price
id
- String - read only
The unique ID of this price.value
- TypedMoneycountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2.customerGroup
- Reference to a CustomerGroup - Optional
A reference to a customer group.channel
- Reference to a Channel - Optional
A reference to a channel.validFrom
- DateTime - Optional
Date from which the price is valid.validUntil
- DateTime - Optional
Date until which the price is valid.tiers
- Array of PriceTier - Optionaldiscounted
- DiscountedPrice - Optional
Set if a matching ProductDiscount exists. If set, the Cart will use the discounted value for the cart price calculation.
When a relative discount is applied and the fraction part of the discounted price is 0.5, the discounted price is rounded in favor of the customer with the half down rounding.custom
- CustomFields - Optional
PriceTier
A price tier is selected instead of the default price when a certain quantity of the ProductVariant is added to a cart and ordered.
For example: the price can be lower if more than 10 items are ordered.
If no price tier is found for the order quantity, the base Price is used.
A price tier is applied for the entire quantity of a product variant put as LineItem in a cart as soon as the minimum quantity for the price tier is reached.
The price tier is applied per line item of the product variant. If, for example, the same product variant appears in the same cart as several line items, (what can be achieved by different values of a custom field on the line items) for each line item the minimum quantity must be reached to get the price tier.
minimumQuantity
- Number
The minimum quantity this price tier is valid for.
The minimum quantity is always greater than or equal to 2 (the base Price is interpreted as valid for minimum quantity equals to 1).- value - TypedMoney
The currency of a price tier is always the same as the currency of the base Price.
DiscountedPrice
value
- CentPrecisionMoneydiscount
- Reference to a ProductDiscount
ScopedPrice
Scoped price is returned as a part of a variant in product search (when price selector is used).
id
- String - read only
The unique ID of this price.value
- TypedMoney - the original price valuecurrentValue
- TypedMoney - either the original pricevalue
or thediscounted
value, if it's availablecountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2.customerGroup
- Reference to a CustomerGroup - Optional
A reference to a customer group.channel
- Reference to a Channel - Optional
A reference to a channel.validFrom
- DateTime - Optional
Date from which the price is valid.validUntil
- DateTime - Optional
Date until which the price is valid.discounted
- DiscountedPrice - Optional
Is set if a matching ProductDiscount exists. If set, the Cart will use the discounted value for the cart price calculation.
When a relative discount is applied and the fraction part of the discounted price is 0.5, the discounted price is rounded in favor of the customer with the half down rounding.custom
- CustomFields - Optional
ProductDraft
The representation sent to the server when creating a new product.
key
- String - Optional
User-specific unique identifier for the product.name
- LocalizedString - RequiredproductType
- ResourceIdentifier of a ProductType - Required
A predefined product type assigned to the product. All products must have a product type.slug
- LocalizedString - Required
Human-readable identifiers usually used as deep-link URLs for the product. A slug must be unique across a project, but a product can have the same slug for different languages. Slugs have a maximum size of 256.
Valid characters are: alphabetic characters (A-Z, a-z
), numeric characters (0-9
), underscores (_
) and hyphens (-
).description
- LocalizedString - Optionalcategories
- Array of ResourceIdentifier for a Category - Optional
Categories assigned to the product.categoryOrderHints
- CategoryOrderHints - OptionalmetaTitle
- LocalizedString - OptionalmetaDescription
- LocalizedString - OptionalmetaKeywords
- LocalizedString - OptionalmasterVariant
- ProductVariantDraft - Optional
The master product variant. Required if thevariants
array has product variants.variants
- Array of ProductVariantDraft - Optional
An array of related product variants.taxCategory
- ResourceIdentifier of a TaxCategory - OptionalsearchKeywords
- SearchKeywords - Optionalstate
- ResourceIdentifier of a State - Optionalpublish
- Boolean - Optional, defaults tofalse
Iftrue
, the product is published immediately.
ProductResourceIdentifier
ResourceIdentifier to a Product.
ProductReference
Reference to a Product.
id
- String - The unique ID of the referenced Product.typeId
- String -product
ProductVariantDraft
sku
- String - Optional
SKU must be unique.key
- String - Optional
User-specific unique identifier for the variant.prices
- Array of PriceDraft - Optional
The prices for the variant draft. A maximum number of 100 prices can be specifiedimages
- Array of Image - Optional
External images for the variant draft. You can also upload images to use the commercetools platform's Content Delivery Network.assets
- Array of AssetDraft - Optionalattributes
- Array of Attribute - Optional
The AttributeType determines the format for the attributevalue
to be provided, in particular:- for EnumType and LocalizableEnumType attributes:
- either only the
key
of the EnumValue or of the LocalizedEnumValue is to be used asvalue
- or the complete EnumValue or the complete LocalizedEnumValue is to be used as
value
- either only the
- for LocalizableTextType attributes the LocalizedString object is to be used as
value
- for MoneyType attributes the Money object is to be used as
value
- for SetType attributes the entire
set
object is to be used asvalue
- for NestedType attributes the list of values of all attributes of the nested product is to be used as
value
- for ReferenceType attributes the Reference object is to be used as
value
- for EnumType and LocalizableEnumType attributes:
PriceDraft
value
- Money - Requiredcountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. If not set, the price is valid for any country.customerGroup
- ResourceIdentifier of a CustomerGroup - Optional
The Customer Group to which the Price is targeted.channel
- ResourceIdentifier of a Channel - Optional
Reference to a particular channel withProductDistribution
ChannelRole.discounted
- DiscountedPrice - Optional
Sets a discounted price from an external service. Absolute or relative ProductDiscounts prices are automatically added to a product's Price when created.
The DiscountedPrice must reference a ProductDiscount with:- The
isActive
flag set totrue
. - An
external
ProductDiscountValue. - A
predicate
which matches the ProductVariant the Price is referenced from.
- The
validFrom
- DateTime - Optional
Date from which the price is valid.validUntil
- DateTime - Optional
Date until which the price is valid.tiers
- Array of PriceTier - Optionalcustom
- CustomFieldsDraft - Optional
The custom fields.
Price Selection
The cart addLineItem update action selects a price from the product's prices array based on the currency, country, customer group,channel, and a date. The product-related endpoints also provide the same price selection logic to help the shop to show the right price to the customer.
If the price selection parameter priceCurrency
and any of the price selection parameters priceCountry
, priceCustomerGroup
and priceChannel
are given as a query parameter and a matching price exists, a price
field containing the matching price is added to the ProductVariant of the returned product projections.
Price validity dates are taken into account (see validFrom
and validUntil
in ProductVariant Price).
The price is shown only when the timestamp of the request is within validFrom
- ValidUntil
range.
Changing the Date for Price Selection BETA
The priceDate
parameter overrides the request's timestamp, selecting a valid price from the past or the future.
When priceDate
does not equal the current date, product discounts are not taken into account. For example, if you create a product discount with validity dates in the future, and use priceDate
in the product discount's timeframe, the future price selected will not include the product discount, even if the discount is valid for the date specified in the priceDate
parameter.
Attribute
When using attributes with GraphQL API mutations, you must escape any strings in the value
field: "value" : "\"A value\""
.
name
- Stringvalue
- *
A valid JSON value, based on an AttributeDefinition.
Category Order Hints
Products can have a category order hint for each category they are assigned to. This allows controlling the order of products and how they appear in categories.
The category order hints is a JSON object where the keys are the category IDs, and the values are the corresponding order hint set for that category.
Order hints are strings representing valid number values between 0 and 1 while everything closer to 1 is interpreted as higher than everything closer to 0. Order hints thus always start with 0.
and must never end with a 0
(always write 0.1
but never 0.10
).
Products that have no order hint have an order score below 0
.
Order hints are non-unique. If a subset of products have the same value for order hint in a specific category, the behavior is undetermined.
Images
A product image can be uploaded using the image upload endpoint, or via the Merchant Center . An Image uploaded to the commercetools platform is stored in a Content Delivery Network and it's available in several pre-defined sizes.
If you already have an image stored on an external service, you can save the URL when creating a new product or adding a variant, or you can add it later. An image is represented in the following way:
url
- String
URL of the image in its original size. The URL must be unique within a single variant. It can be used to obtain the image in different sizes - see below.dimensions
-{"w": Number, "h": Number}
Dimensions of the original image. This can be used by your application for example to determine whether the image is large enough to display a zoom view.label
- String - Optional
Custom label that can be used, for example, as an image description.
Images in specific sizes are obtained by appending a size suffix to the original URL (before the .jpg
, .png
etc. extension part of the filename):
-thumb
(50x50) - example-small
(150x150) - example-medium
(400x400) - example-large
(700x700) - example-zoom
(1400x1400) - example- the original size of the uploaded image is provided without a suffix - example
Note that images will never be scaled up. If the original image is tiny, it will keep its original size, even in the "large" and "zoom" sizes.
Also note that images are not shared between variants - each variant has its own set of images. However, if you wish to have many variants with the same set of images, you can implement this in your application by always showing the images of the master variant, regardless of the selected variant.
SearchKeywords
Search keywords are primarily used by the suggester, but are also considered for the full text search. SearchKeywords is a JSON object where the keys are of IETF language tag. The value to a language tag key is an array of SearchKeyword for the specific language.
{"en": [{ "text": "Multi tool" },{ "text": "Swiss Army Knife", "suggestTokenizer": { "type": "whitespace" } }],"de": [{"text": "Schweizer Messer","suggestTokenizer": {"type": "custom","inputs": ["schweizer messer", "offiziersmesser", "sackmesser"]}}]}
SearchKeyword
text
- String
Text to return in the result of a suggest query.suggestTokenizer
- SuggestTokenizer - Optional
If no tokenizer is defined, thetext
is used as single token.
SuggestTokenizer
The tokenizer defines the tokens that are used to match against the suggest query input.
Whitespace Tokenizer
Whitespace tokenizer creates tokens by splitting the SearchKeyword text
field by whitespaces.
type
-whitespace
Custom Tokenizer
Custom tokenizer allows to define arbitrary tokens which are used to match the input.
type
-custom
inputs
- Array of String
Contains custom tokens
Get Product
Get Product by ID
Gets the full representation of a product by ID.
Endpoint: /{projectKey}/products/{id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: Product
Query Parameters:
priceCurrency
- String - Optional
The currency code compliant to ISO 4217. Enables price selection.priceCountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.
#!/bin/sh$curl "https://api.{region}.commercetools.com/{projectKey}/products/e7ba4c75-b1bb-483d-94d8-2c4a10f78472" \-H "Authorization: Bearer YrT7pRnLXVIco7KHlere_X-HL0sWdWOE"
{"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472","masterData": {"current": {"categories": [{"id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb","typeId": "category"}],"description": {"en": "Sample description"},"masterVariant": {"attributes": [],"id": 1,"images": [{"dimensions": {"h": 1400,"w": 1400},"url": "https://example.com/cli/data/253245821_1.jpg"}],"prices": [{"value": {"centAmount": 10000,"currencyCode": "EUR"}}],"sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"},"name": {"en": "MB PREMIUM TECH T"},"slug": {"en": "mb-premium-tech-t1369226795424"},"variants": [],"searchKeywords": {}},"hasStagedChanges": false,"published": true,"staged": {"categories": [{"id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb","typeId": "category"}],"description": {"en": "Sample description"},"masterVariant": {"attributes": [],"id": 1,"images": [{"dimensions": {"h": 1400,"w": 1400},"url": "https://example.com/cli/data/253245821_1.jpg"}],"prices": [{"value": {"centAmount": 10000,"currencyCode": "EUR"}}],"sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"},"name": {"en": "MB PREMIUM TECH T"},"slug": {"en": "mb-premium-tech-t1369226795424"},"variants": [],"searchKeywords": {}}},"productType": {"id": "24f510c3-f334-4099-94e2-d6224a8eb919","typeId": "product-type"},"taxCategory": {"id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59","typeId": "tax-category"},"version": 2}
Get Product by Key
Gets the full representation of a product by Key.
Endpoint: /{projectKey}/products/key={key}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: Product
Query Parameters:
priceCurrency
- String - Optional
The currency code compliant to ISO 4217. Enables price selection.priceCountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.
Query Products
You can use the query endpoint to get the full representations of products. We suggest to use the performance optimized search endpoint which has a bunch functionalities, the query API lacks like sorting on custom attributes, etc.
Endpoint: /{projectKey}/products
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with results
containing an array of Product
Query Parameters:
where
- Query Predicate - Optional
The predicate on product attributes is limited totext
,enum
,boolean
,number
,date
,time
anddatetime
attribute types.sort
- Sort - Optional
Sorting is only possible for data not nested in arrays. Examples are: SKU of masterVariant, createdAt, lastModifiedAt, name.en, etc. Sorting for prices or custom attributes via Query API is not possible.expand
- Expansion - Optionallimit
- Number - Optionaloffset
- Number - OptionalpriceCurrency
- String - Optional
The currency code compliant to ISO 4217. Enables price selection.priceCountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.
#!/bin/sh$curl "https://api.{region}.commercetools.com/{projectKey}/products?where=masterData%28current%28name%28en%3D%22MB%20PREMIUM%20TECH%20T%22%29%29%29%20and%20id%20%3D%20%22e7ba4c75-b1bb-483d-94d8-2c4a10f78472%22" \-H "Authorization: Bearer YrT7pRnLXVIco7KHlere_X-HL0sWdWOE"# decoded query:# masterData(current(name(en="MB PREMIUM TECH T"))) and id = "e7ba4c75-b1bb-483d-94d8-2c4a10f78472"
{"count": 1,"offset": 0,"results": [{"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472","masterData": {"current": {"categories": [{"id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb","typeId": "category"}],"description": {"en": "Sample description"},"masterVariant": {"attributes": [],"id": 1,"images": [{"dimensions": {"h": 1400,"w": 1400},"url": "https://example.com/cli/data/253245821_1.jpg"}],"prices": [{"value": {"centAmount": 10000,"currencyCode": "EUR"}}],"sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"},"name": {"en": "MB PREMIUM TECH T"},"slug": {"en": "mb-premium-tech-t1369226795424"},"variants": [],"searchKeywords": {}},"hasStagedChanges": false,"published": true,"staged": {"categories": [{"id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb","typeId": "category"}],"description": {"en": "Sample description"},"masterVariant": {"attributes": [],"id": 1,"images": [{"dimensions": {"h": 1400,"w": 1400},"url": "https://example.com/cli/data/253245821_1.jpg"}],"prices": [{"value": {"centAmount": 10000,"currencyCode": "EUR"}}],"sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"},"name": {"en": "MB PREMIUM TECH T"},"slug": {"en": "mb-premium-tech-t1369226795424"},"variants": [],"searchKeywords": {}}},"productType": {"id": "24f510c3-f334-4099-94e2-d6224a8eb919","typeId": "product-type"},"taxCategory": {"id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59","typeId": "tax-category"},"version": 2}],"total": 1}
Query Product Selections for a Product BETA
Retrieves the Product Selections that contain the given Product.
Query Product Selections for a Product by Key
Endpoint: /{projectKey}/products/key={key}/product-selections
Method: GET
OAuth 2.0 Scopes: view_product_selections:{projectKey}
Response Representation: PagedQueryResult with results
containing an array of AssignedProductSelection
Query Parameters:
where
- Query Predicate - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- Number - Optional
Query Product Selections for a Product by ID
Endpoint: /{projectKey}/products/{id}/product-selections
Method: GET
OAuth 2.0 Scopes: view_product_selections:{projectKey}
Response Representation: PagedQueryResult with results
containing an array of AssignedProductSelection
Query Parameters:
where
- Query Predicate - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- Number - Optional
Check existence of Products
By Id
Endpoint: /{projectKey}/products/{id}
Method: HEAD
OAuth 2.0 Scopes: view_products:{projectKey}
Response Status: 200 OK
if the product with given ID exists, 404 Not Found
otherwise
By Key
Endpoint: /{projectKey}/products/key={key}
Method: HEAD
OAuth 2.0 Scopes: view_products:{projectKey}
Response Status: 200 OK
if the product with given key exists, 404 Not Found
otherwise
By Query Predicate
Endpoint: /{projectKey}/products
Method: HEAD
OAuth 2.0 Scopes: view_products:{projectKey}
Response Status: 200 OK
if at least one product exists matching the query condition, 404 Not Found
in case no product matches the query condition.
Query Parameters:
where
- Query Predicate - Optional
The predicate on product attributes is limited totext
,enum
,boolean
,number
,date
,time
anddatetime
attribute types.
Create a Product
To create a new product, send a representation that is going to become the initial staged representation of the new product in the master catalog. If price selection query parameters are provided, the selected prices will be added to the response.
Endpoint: /{projectKey}/products
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Request Representation: ProductDraft
Response Representation: Product
Query Parameters:
priceCurrency
- String - Optional
The currency code compliant to ISO 4217. Enables price selection.priceCountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.
Creating a product produces the ProductCreatedMessage.
Update Product
(Partial) updates are made to an existing product by sending a list of actions to be applied.
The actions are applied in the given order. If price selection query parameters are provided,
the selected prices will be added to the response.
Update Product by ID
Endpoint: /{projectKey}/products/{id}
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:
priceCurrency
- String - Optional
The currency code compliant to ISO 4217. Enables price selection.priceCountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.
Fields:
version
- Number - Required
The expected version of the product on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.actions
- Array of UpdateAction - Required
The list of update actions to apply to the product.
Specific Error Codes:
Update Product by Key
Update a product found by its Key.
Endpoint: /{projectKey}/products/key={key}
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:
priceCurrency
- String - Optional
The currency code compliant to ISO 4217. Enables price selection.priceCountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.
Fields:
version
- Number - Required
The expected version of the product on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.actions
- Array of UpdateAction - Required
The list of update actions to apply to the product.
Specific Error Codes:
Update actions
Set Key
action
- String -"setKey"
key
- String - Optional
Ifkey
is absent ornull
, the existing key, if any, will be removed.
Change Name
action
- String -"changeName"
name
- LocalizedString - Requiredstaged
- Boolean - Optional (Default:true
)
Set Description
action
- String -"setDescription"
description
- LocalizedString - Optional
If the field already exists and the value is omitted or set tonull
, the field will be removed.staged
- Boolean - Optional (Defaults totrue
)
Change Slug
action
- String -"changeSlug"
slug
- LocalizedString - Required
Every slug must be unique across a project, but a product can have the same slug for different languages. Allowed are alphabetic, numeric, underscore (_
) and hyphen (-
) characters. Maximum size is 256.staged
- Boolean - Optional (Defaults totrue
)
Changing the slug produces the ProductSlugChangedMessage.
Add ProductVariant
action
- String -"addVariant"
sku
- String - Optional
SKU must be unique.key
- String - Optional
User-specific unique identifier for the variant.prices
- Array of Price - Optional. A maximum number of 100 prices can be specified on a ProductVariant.images
- Array of Image - Optional
External images for the new variant. You can also upload images to use the commercetools platform's Content Delivery Network.attributes
- Array of Object - Optional
The custom attributes of the master variant. Each attribute is a JSON object where a fieldname
corresponds to the name of a product attribute defined on the referenced ProductType and thevalue
being a valid JSON value for that attribute.staged
- Boolean - Optional (Defaults totrue
)assets
- Array of Asset - Optional
Remove ProductVariant
action
- String -"removeVariant"
id
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Defaults totrue
)
Removing a product variant produces the ProductVariantDeletedMessage.
Change Master Variant
Sets the given variant as the new master variant. The previous master variant is added to the back of the list of variants.
action
- String -"changeMasterVariant"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Defaults totrue
)
Add Price
Adds the given price to the product variant's prices set.
Prices are defined with a scope (currency and optionally country, CustomerGroup, and Channel and/or a validity period (validFrom
and/or validTo
).
For more information see price selection.
Adding a price is rejected:
- if the product already contains a price with the same price scope (same currency, country, customer group, and channel).
- if two prices have validity periods that overlap within the same price scope. A price without validity period does not conflict with a price defined for a time period.
A maximum number of 100 prices can be specified on a ProductVariant.
To keep the number of prices per Product Variant low, make use of the price selection fallback logic. For example, you can define a single price for all countries using the EUR
currency instead of defining prices for the individual country
attributes. Similarly, you can define a price without a channel
attribute to use as a base price across channels, and create additional prices with a channel
attribute for specific channels that differ from the base price.
action
- String -"addPrice"
variantId
- Number orsku
- String - Requiredprice
- PriceDraft - Requiredstaged
- Boolean - Optional (Defaults totrue
)
Set Prices
Sets the prices of a product variant. The same validation rules as for addPrice apply. All previous price information is lost and even if some prices did not change, all the prices will have new IDs. A maximum number of 100 prices can be specified on a ProductVariant.
action
- String -"setPrices"
variantId
- Number orsku
- String - Requiredprices
- Array of PriceDraft - Requiredstaged
- Boolean - Optional (Defaults totrue
)
Change Price
Replaces a price in the product variant's prices set. The price to replace is specified by its ID.
action
- String -"changePrice"
priceId
- String - Required
ID of the Priceprice
- PriceDraft - Requiredstaged
- Boolean - Optional (Defaults totrue
)
Remove Price
action
- String -"removePrice"
priceId
- String - Required
ID of the Pricestaged
- Boolean - Optional (Defaults totrue
)
Set Price Custom Type
This action sets, overwrites, or removes any existing custom type and fields for an existing product price.
action
- String -"setProductPriceCustomType"
type
- ResourceIdentifier of a Type - Optional
If set, the custom type is set to this new value.
If absent, the custom type and any existing custom fields are removed.priceId
- String - Requiredstaged
- Boolean - Optional (Defaults totrue
)fields
- A valid JSON object, based on the FieldDefinitions of the Type - Optional
If set, the CustomFields are set to this new value.
Set Price CustomField
This action sets, overwrites, or removes any existing custom field for an existing product price.
action
- String -"setProductPriceCustomField"
priceId
- String - Requiredstaged
- Boolean - Optional (Defaults totrue
)name
- String - Requiredvalue
- Value - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. Ifvalue
is provided, set thevalue
of the field defined by thename
.
Set Discounted Price
Discounts a product price. The referenced ProductDiscount in the discounted
field must be of type external
, active, and its predicate must match the referenced price.
action
- String -"setDiscountedPrice"
priceId
- String - Requiredstaged
- Boolean - Optional (Defaults totrue
)discounted
- DiscountedPrice - Optional
The set discounted value will be unset or replaced
- when no
discounted
property is provided - once a matching relative or absolute product discount with a higher sortOrder exists,
- if the referenced external discount is deactivated, or
- if the product changes and the external product discount predicate does not match the discounted price any more.
Produces the ProductPriceExternalDiscountSetMessage.
Set Attribute
Adds/Removes/Changes a custom attribute.
action
- String -"setAttribute"
variantId
- Number orsku
- String - Requiredname
- String - Requiredvalue
- * - Optional
If the attribute exists and the value is omitted or set tonull
, the attribute is removed. If the attribute exists and a value is provided, the new value is applied. If the attribute does not exist and a value is provided, it is added as a new attribute.
The AttributeType determines the format for thevalue
to be provided, in particular:- for EnumType and LocalizableEnumType attributes:
- either only the
key
of the EnumValue or of the LocalizedEnumValue is to be used asvalue
- or the complete EnumValue or the complete LocalizedEnumValue is to be used as
value
- either only the
- for LocalizableTextType attributes the LocalizedString object is to be used as
value
- for MoneyType attributes the Money object is to be used as
value
- for SetType attributes the entire
set
object is to be used asvalue
- for NestedType attributes the list of values of all attributes of the nested product is to be used as
value
- for ReferenceType attributes the Reference object is to be used as
value
- for EnumType and LocalizableEnumType attributes:
staged
- Boolean - Optional (Default istrue
)
Set Attribute In All Variants
Adds / Removes / Changes a custom attribute in all variants at the same time (it can be helpful to set attribute values that are constrained with SameForAll).
action
- String -"setAttributeInAllVariants"
name
- String - Requiredvalue
- * - Optional
The same update behavior as for Set Attribute applies.staged
- Boolean - Optional (Default istrue
)
Add to Category
action
- String -"addToCategory"
category
- ResourceIdentifier of a Category - RequiredorderHint
- String - OptionalString representing a number which is greater than 0 and smaller than 1. It should start with
0.
and should not end with0
. Valid examples:0.1
,0.123456
. Invalid examples:0
,1
,0.10
,0.1234560
,0.12345e7
.staged
- Boolean - Optional (Default istrue
)
Adding a product to a category produces the ProductAddedToCategoryMessage.
Set Category Order Hint
action
- String -"setCategoryOrderHint"
categoryId
- Id of a Category the product belongs to - RequiredorderHint
- String - Optional (If left blank, the category order hint is unset/removed.)String representing a number which is greater than 0 and smaller than 1. It should start with
0.
and should not end with0
. Valid examples:0.1
,0.123456
. Invalid examples:0
,1
,0.10
,0.1234560
,0.12345e7
.staged
- Boolean - Optional (Default istrue
)
Remove from Category
action
- String -"removeFromCategory"
category
- ResourceIdentifier of a Category - Requiredstaged
- Boolean - Optional (Default istrue
)
Removing a product from a category produces the ProductRemovedFromCategoryMessage.
Set TaxCategory
Adds, changes, or removes a product's TaxCategory. This change can never be staged and is thus immediately visible in published products.
action
- String -"setTaxCategory"
taxCategory
- ResourceIdentifier of a TaxCategory - Optional
If left blank or set tonull
, the tax category is unset/removed.
Set SKU
Adds, changes, or removes a SKU on a product variant. A SKU can only be changed or removed from a variant through this operation if there is no inventory entry associated with that SKU.
action
- String -"setSku"
variantId
- Numbersku
- String - Optional
SKU must be unique. If left blank or set tonull
, the SKU is unset/removed.staged
- Boolean - Optional (Defaults totrue
)
Set ProductVariant Key
Adds, changes, or removes a key on a product variant.
action
- String -"setProductVariantKey"
variantId
- Number orsku
- String - Requiredkey
- String - Optional
If left blank or set tonull
, the key is unset/removed.staged
- Boolean - Optional (Defaults totrue
)
Add External Image
Adds an external image URL with meta-information to the product variant.
action
- String -"addExternalImage"
variantId
- Number orsku
- String - Requiredimage
- Image - Requiredstaged
- Boolean - Optional (Defaults totrue
)
Adding an external image produces the ProductImageAddedMessage.
Move Image To Position
Moves an image to a new position within a product variant.
action
- String -"moveImageToPosition"
variantId
- Number orsku
- String - RequiredimageUrl
- String- Required
The URL of the imageposition
- Number - Requiredstaged
- Boolean - Optional (Defaults totrue
)
Remove Image
Removes a product image and deletes it from the Content Delivery Network (it would not be deleted from the CDN in case of external image). Deletion from the CDN is not instant, which means the image file itself will stay available for some time after the deletion.
action
- String -"removeImage"
variantId
- Number orsku
- String - RequiredimageUrl
- String- Required
The URL of the image.staged
- Boolean - Optional (Defaults totrue
)
Set Image Label
action
- String -"setImageLabel"
variantId
- Number orsku
- String - RequiredimageUrl
- String - Required
The URL of the image.label
- String - Optional
The new image label. If left blank or set to null, the label is removed.staged
- Boolean - Optional (Defaults totrue
)
Add Asset
Adds an Asset.
action
- String -"addAsset"
variantId
- Number orsku
- String - Requiredposition
- Number - Optional
Position of the new asset inside the existing list (from0
to the size of the list)staged
- Boolean - Optional (Default istrue
)asset
- AssetDraft
Remove Asset
Removes an Asset.
action
- String -"removeAsset"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Required
Set Asset Key
Set or remove the key
of an Asset.
action
- String -"setAssetKey"
variantId
- Integer orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String - RequiredassetKey
- String - Optional
User-defined identifier for the asset.
If left blank or set tonull
, the asset key is unset/removed.
Change Asset Order
Changes the order of the assets
array. The new order is defined by listing the id
s of the assets.
action
- String -"changeAssetOrder"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetOrder
- Array of String - Must contain all assetid
s.
Change Asset Name
action
- String -"changeAssetName"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredname
- LocalizedString - Required
Set Asset Description
action
- String -"setAssetDescription"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requireddescription
- LocalizedString - Optional
Set Asset Sources
action
- String -"setAssetSources"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredsources
- Array of AssetSource - Requires at least one entry
Set Asset Custom Type
This action sets, overwrites, or removes the custom type and fields for an existing Asset.
action
- String -"setAssetCustomType"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredtype
- ResourceIdentifier of a Type - Optional
If set, the custom type is set to this new value.
If absent, the custom type and any existing custom fields are removed.fields
- A valid JSON object, based on the FieldDefinitions of the Type - Optional
If set, the custom fields are set to this new value.
Set Asset Custom Field
This action sets, overwrites, or removes any existing custom field for an existing Asset.
action
- String -"setAssetCustomField"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredname
- String - Requiredvalue
- Value - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. Ifvalue
is provided, set thevalue
of the field defined by thename
.
Set SearchKeywords
action
- String -"setSearchKeywords"
searchKeywords
- SearchKeywords - Requiredstaged
- Boolean - Optional (Default istrue
)
Set Meta Title
action
- String -"setMetaTitle"
metaTitle
- LocalizedString - Optionalstaged
- Boolean - Optional (Default istrue
)
Set Meta Description
action
- String -"setMetaDescription"
metaDescription
- LocalizedString - Optionalstaged
- Boolean - Optional (Default istrue
)
Set Meta Keywords
action
- String -"setMetaKeywords"
metaKeywords
- LocalizedString - Optionalstaged
- Boolean - Optional (Default istrue
)
Revert Staged Changes
Revert all changes, which were made to the staged version of a product and reset to the current version.
action
- String -"revertStagedChanges"
Reverting staged changes produces the ProductRevertedStagedChangesMessage.
Revert Staged Variant Changes
Revert changes of a variant, which were made to the staged version of a product and reset to the current version.
action
- String -"revertStagedVariantChanges"
variantId
- Integer - Required
Publish
Publishing a product produces the ProductPublishedMessage.
Publish with scope "All"
Publishes a product, which causes the staged projection of the product to override the current projection. If the product is published for the first time, the current projection is created.
Publish with scope "Prices"
Publishes only the product prices.
Publishing the prices is only possible if the product is currently published.
All prices found on variants in the staged projection are published into
variants found in the current projection with the same id
.
Prices found on a staged variant that has no current projection are not published.
Prices found on a current variant that has no staged projection are unchanged.
The flag hasStagedChanges
is updated according to whether the staged and the current projections still differ after the prices publishing.
Unpublish
Unpublishes a product, effectively deleting the current projection of the product,
leaving only the staged projection. When a product is unpublished,
it will no longer be included in query or search results issued with staged=false
,
since such results only include current projections.
action
- String -"unpublish"
Unpublishing a product produces the ProductUnpublishedMessage.
Transition State
Transition to a new state. If there is no state yet, the new state must be an initial state. If the existing state has transitions
set, there must be a direct transition to the new state. If transitions
is not set, no validation is performed. These validations can be turned off by setting the force
parameter to true
.
action
- String -"transitionState"
state
- Reference to a Stateforce
- Boolean - Optional - Defaults tofalse
Transitioning the state of a product produces the ProductStateTransitionMessage.
Upload a product image
Uploads a binary image file to a given product variant. The supported image formats are JPEG, PNG, and GIF. The file size of the image is limited to 10 MB.
Endpoint: /{projectKey}/products/{id}/images
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: Product
Headers:
Content-Type
- one of"image/jpeg"
,"image/png"
or"image/gif"
.
Query Parameters:
variant
- Number orsku
- String - Optional
The variant to which the image should be added. Defaults to the master variant if neither is given.filename
- String - Optional (Defaults to"img"
)
Name under which the image should be stored in the Content Delivery Network. The name doesn't need to be unique - see below. The filename should be URL-encoded.staged
- Boolean - Optional (Defaults totrue
)
Whether to update the staged or current projection of the product.
Body: The raw binary data.
An example using cURL:
curl -X POST \-H "Content-Type: image/jpeg" \-H "Authorization: Bearer {token}" \--upload-file "detail.jpg" \"https://api.{region}.commercetools.com/{projectKey}/products/{id}/images?variant=2&filename=detail.jpg"
This adds an Image to the variant with id = 2, in the staged projection of the product.
Since the parameter filename=detail.jpg
was specified, the URL of the uploaded image will be for example
https://{sphere-cdn}/detail-6xAq4Efp.jpg
. If you don't specify a custom filename a random one will be chosen.
The uploaded image is available in several sizes.
Note that a 200 OK
response with a Product is returned as soon as the Small
version of the image has been uploaded to the CDN. The other sizes might not be available immediately after a response is returned but only after a short delay.
Note that file upload using Content-Type: multipart/form-data is currently not supported.
Uploading an image produces the ProductImageAddedMessage. The message will be produced as soon as the Small
version of the image has been uploaded to the CDN.
Images loaded on one product and then reused on another product or project may loose images when the original product is removed.
Delete Product
To be able to delete a product this has to be unpublished upfront.
If price selection query parameters are provided, the selected prices will be added to the response.
Deleting a product produces the ProductDeletedMessage.
Delete Product by ID
Endpoint: /{projectKey}/products/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: Product
Query Parameters:
version
- Number - RequiredpriceCurrency
- String - Optional
The currency code compliant to ISO 4217. Enables price selection.priceCountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.
Delete Product by Key
Delete a product found by its Key.
Endpoint: /{projectKey}/products/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: Product
Query Parameters:
version
- Number - RequiredpriceCurrency
- String - Optional
The currency code compliant to ISO 4217. Enables price selection.priceCountry
- String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.