This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Products

Products represent the sellable goods in an e-commerce project.

Products contain ProductVariants, which represent a single sellable product (often an individual SKU). Efficiently mapping your goods to Products and ProductVariants is an important part of working with the API. For more information, see the Product Modeling Module.

The ProductPriceMode controls whether the prices are embedded into the Product Variants (up to 100 per Product Variant) or stored separately as StandalonePrice (up to 50 000 per Product Variant).

Learn more about Products in our self-paced Product data modeling module.

Representations

Product

An abstract sellable good with a set of Attributes defined by a Product Type. Products themselves are not sellable. Instead, they act as a parent structure for Product Variants. Each Product must have at least one Product Variant, which is called the Master Variant. A single Product representation contains the current and the staged representation of its product data.

id
String

Unique identifier of the Product.

version
Int

Current version of the Product.

key
String

User-defined unique identifier of the Product.

This is different from the key of a ProductVariant.

productType

The Product Type defining the Attributes of the Product. Cannot be changed.

masterData

Contains the current and the staged representation of the product information.

taxCategory

The TaxCategory of the Product.

state

State of the Product.

reviewRatingStatistics

Review statistics of the Product.

priceMode

Type of Price to be used when looking up a price for the Product.

Default: Embedded
createdAt

Date and time (UTC) the Product was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the Product was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

Example: json
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 2,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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"
},
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

ProductDraft

key
String

User-defined unique identifier for the Product.

The Product Type defining the Attributes for the Product. Cannot be changed later.

name

Name of the Product.

slug

User-defined identifier used in a deep-link URL for the Product. It must be unique across a Project, but a Product can have the same slug in different Locales. It must match the pattern [a-zA-Z0-9_-]{2,256}.

description

Description of the Product.

categories

Categories assigned to the Product.

categoryOrderHints

Numerical values to allow ordering of Products within a specified Category.

metaTitle

Title of the Product displayed in search results.

metaDescription

Description of the Product displayed in search results.

metaKeywords

Keywords that give additional information about the Product to search engines.

masterVariant

The Product Variant to be the Master Variant for the Product. Required if variants are provided also.

variants

The additional Product Variants for the Product.

The Tax Category to be assigned to the Product.

searchKeywords

Used by Product Suggestions, but is also considered for a full text search.

State to be assigned to the Product.

publish
Boolean

If true, the Product is published immediately to the current projection.

Default: false
priceMode

Specifies the type of prices used when looking up a price for the Product.

Default: Embedded
Example: json
{
"productType": {
"id": "24f510c3-f334-4099-94e2-d6224a8eb919",
"typeId": "product-type"
},
"categories": [
{
"typeId": "category",
"id": "24f510c3-f334-4099-94e2-d6224a8eb919"
}
],
"name": {
"en": "Some Product"
},
"slug": {
"en": "product_slug_<random-uuid>"
},
"masterVariant": {
"sku": "SKU-1",
"prices": [
{
"value": {
"currencyCode": "EUR",
"centAmount": 4200
}
}
],
"images": [
{
"url": "http://my.custom.cdn.net/master.png",
"label": "Master Image",
"dimensions": {
"w": 303,
"h": 197
}
}
]
},
"variants": [
{
"images": [
{
"url": "http://my.custom.cdn.net/variant.png",
"label": "Variant Image",
"dimensions": {
"w": 303,
"h": 197
}
}
]
}
]
}

ProductPagedQueryResponse

PagedQueryResult with results containing an array of Product.

limit
Int
offset
Int

Number of elements skipped.

count
Int

Actual number of results returned.

total
Int

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results
Array of Product

Products matching the query.

ProductReference

id
String

Unique identifier of the referenced Product.

typeId
String
"product"

References a Product.

obj

Contains the representation of the expanded Product. Only present in responses to requests with Reference Expansion for Products.

ProductResourceIdentifier

ResourceIdentifier to a Product. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

id
String

Unique identifier of the referenced Product. Required if key is absent.

key
String

User-defined unique identifier of the referenced Product. Required if id is absent.

typeId
String
"product"

References a Product.

ProductCatalogData

Contains the current and staged ProductData.

published
Boolean

true if the Product is published.

current

Current (published) data of the Product.

staged

Staged (unpublished) data of the Product.

hasStagedChanges
Boolean

true if the staged data is different from the current data.

ProductData

Contains all the data of a Product and its Product Variants.

name

Name of the Product.

categories
Array of CategoryReference

Categories assigned to the Product.

categoryOrderHints

Numerical values to allow ordering of Products within a specified Category.

description

Description of the Product.

slug

User-defined identifier used in a deep-link URL for the Product. Must be unique across a Project, but can be the same for Products in different Locales. Matches the pattern [a-zA-Z0-9_-]{2,256}.

metaTitle

Title of the Product displayed in search results.

metaDescription

Description of the Product displayed in search results below the meta title.

metaKeywords

Keywords that give additional information about the Product to search engines.

masterVariant

The Master Variant of the Product.

variants
Array of ProductVariant

Additional Product Variants.

searchKeywords

Used by Product Suggestions, but is also considered for a full text search.

CategoryOrderHints

JSON object where the key is a Category id and the value is an order hint. Allows controlling the order of Products and how they appear in Categories. Products with 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.

/[0-9].[0-9]*[1-9]/
Any string property matching this regular expression

A string representing a number between 0 and 1 that must start with 0. and cannot end with 0.

Example: json
{
"categoryOrderHints": {
"7bcd33e6-c1c7-4b96-8d70-9b9b18b19b70": "0.992"
}
}

SearchKeywords

Search keywords are primarily used by Product Suggestions, but are also considered for a full-text search. SearchKeywords is a JSON object where the keys are of type Locale and the values are an array of SearchKeyword.

{
"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

If no tokenizer is defined, the text is used as a single token.

SuggestTokenizer

Defines tokens that are used to match against the suggest query input. Can be differentiated by the type field.

Whitespace Tokenizer

Creates tokens by splitting the text field in SearchKeyword by whitespaces.

type
String
"whitespace"

Custom Tokenizer

Define arbitrary tokens that are used to match the input.

type
String
"custom"
inputs
Array of String

Contains custom tokens.

ProductVariant

A concrete sellable good for which inventory can be tracked. Product Variants are generally mapped to specific SKUs.

id
Int

A unique, sequential identifier of the Product Variant within the Product.

key
String

User-defined unique identifier of the ProductVariant.

This is different from Product key.

sku
String

User-defined unique SKU of the Product Variant.

prices
Array of Price

The Embedded Prices of the Product Variant. Cannot contain two Prices of the same Price scope (with same currency, country, Customer Group, Channel, validFrom and validUntil).

attributes
Array of Attribute

Attributes of the Product Variant.

price

Only available when Price selection is used. Cannot be used in a Query Predicate.

images
Array of Image

Images of the Product Variant.

assets
Array of Asset

Media assets of the Product Variant.

availability

Set if the Product Variant is tracked by Inventory. Can be used as an optimization to reduce calls to the Inventory service. May not contain the latest Inventory State (it is eventually consistent).

isMatchingVariant
Boolean

true if the Product Variant matches the search query. Only available in response to a Product Projection Search request.

scopedPrice

Only available in response to a Product Projection Search request with price selection. Can be used to sort, filter, and facet.

scopedPriceDiscounted
Boolean

Only available in response to a Product Projection Search request with price selection.

ProductVariantDraft

Creates a Product Variant when included in the masterVariant and variants fields of the ProductDraft.

key
String

User-defined unique identifier for the ProductVariant.

sku
String

User-defined unique SKU of the Product Variant.

prices
Array of PriceDraft

The Embedded Prices for the Product Variant. Each Price must have its unique Price scope (with same currency, country, Customer Group, Channel, validFrom and validUntil).

MaxItems: 100
attributes
Array of Attribute

Attributes according to the respective AttributeDefinition.

images
Array of Image

Images for the Product Variant.

assets
Array of AssetDraft

Media assets for the Product Variant.

Attribute

When using attributes with GraphQL API mutations, you must escape any strings in the value field: "value" : "\"A value\"".

name
String

Name of the Attribute.

value
Any

The AttributeType determines the format of the Attribute value to be provided:

Image

Product images can be uploaded using the image upload endpoint or the Merchant Center. An image uploaded to commercetools Composable Commerce is stored in a Content Delivery Network and is 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 ProductVariant, or you can add it later. An image is represented in the following way:

url
String

URL of the image in its original size that must be unique within a single ProductVariant. If the Project is hosted in the China (AWS, Ningxia) Region, verify that the URL is not blocked due to firewall restrictions.

dimensions

Dimensions of the original image.

label
String

Custom label for the image.

Images in specific sizes are obtained by adding a size suffix before the filename extension:

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.

ProductVariants do not share images. To use the same set of images for multiple ProductVariants, you can implement this in your application by always showing the images of the Master Variant, regardless of the selected ProductVariant.

ImageDimensions

w
Int

Width of the image.

h
Int

Height of the image.

ProductVariantAvailability

The InventoryEntry information of the Product Variant. If there is a supply Channel for the InventoryEntry, then channels is returned. If not, then isOnStock, restockableInDays, and quantityOnStock are returned.

For each InventoryEntry with a supply Channel, an entry is added to channels.

isOnStock
Boolean

Indicates whether a Product Variant is in stock.

restockableInDays
Int

Number of days to restock a Product Variant once it is out of stock.

availableQuantity
Int

Number of items of the Product Variant that are in stock.

ProductVariantChannelAvailabilityMap

A JSON object where the key is a supply Channel id and the value is the ProductVariantChannelAvailability of the InventoryEntry.

{
"cd724bd4-52fa-4d6d-b4b0-bb1560d70475": {
"isOnStock": true,
"restockableInDays": 10,
"availableQuantity": 20,
"version": 1,
"id": "f64af276-a1ad-4eea-a8bc-89c453742a40"
}
}

ProductVariantChannelAvailability

id
String

Unique identifier of the InventoryEntry.

version
Int

Current version of the InventoryEntry.

isOnStock
Boolean

Indicates whether a Product Variant is in stock in a specified Channel.

restockableInDays
Int

Number of days to restock a Product Variant once it is out of stock in a specified Channel.

availableQuantity
Int

Number of items of this Product Variant that are in stock in a specified Channel.

ProductPriceMode

This mode determines the type of Prices used for Product Price Selection and for LineItem Price selection.

Embedded

Composable Commerce uses the Embedded Prices located inside the prices field in ProductVariant.

Standalone

Composable Commerce uses StandalonePrices, which are associated with the ProductVariant through the sku field.

Changing the Price mode does not change the behavior of the update actions Add Price, Set Prices, Change Price and Remove Price, which are only meant for managing Embedded Prices.

The prices array in ProductVariant contains only Embedded Prices regardless of the current Price mode.

No migration from Embedded Prices to StandalonePrices (or vice versa) takes place when changing the Price mode of a Product.

Embedded Price

A Price contained in the Product Variant's prices field is called Embedded Price. In contrast, a StandalonePrice is not embedded into a Product Variant, but associated to it through the sku field.

Price selection

When adding a Product Variant to the Cart, commercetools Composable Commerce selects a Price associated with that Product Variant as indicated by the Product's priceMode and based on the Customer's Cart's currency, country, customerGroup, distributionChannel, and a date. Product-related endpoints provide the same price selection logic to present the most appropriate price to Customers before adding the Product Variants to the Carts.

To utilize this, the priceCurrency query parameter is provided together with other Price Selection Parameters, like priceCountry, priceCustomerGroup or priceChannel on the Product Projections API or on the Product Projection Search endpoint.

The Price for which most of the Price Selection Parameters match is contained in the price field added to the ProductVariant returned in response to the aforementioned API calls.

Price validity dates are taken into account (see validFrom and validUntil in Price and StandalonePrice).

The Price is shown only when the timestamp of the request is within validFrom - validUntil range.

Filtering, faceting, and sorting is not supported for Standalone Prices.

Please note that existing filters, faceting, and sorting options still work, but will only consider Embedded Prices, therefore using these options on Products with Standalone ProductPriceMode might yield inconsistent results.

ScopedPrice

Scoped Price is contained in a ProductVariant which is returned in response to a Product Projection Search request when Scoped Price Search is used.

id
String

Platform-generated unique identifier of the Price.

value

Original value of the Price.

currentValue

If available, either the original price value or discounted value.

country

Country code of the geographic location.

Pattern: ^[A-Z]{2}$
customerGroup

Reference to a CustomerGroup.

channel

Reference to a Channel.

validFrom

Date and time from which the Price is valid.

validUntil

Date and time until which the Price is valid.

discounted

Is set when a matching ProductDiscount exists. If set, the Cart uses the discounted value for the Cart Price calculation.

When a relative Product Discount is applied and the fractional part of the discounted Price is 0.5, the discounted Price is rounded half down in favor of the Customer.

custom

Custom Fields for the Price.

Get Product

Get Product by ID

GET
https://api.{region}.commercetools.com/{projectKey}/products/{id}

If Price selection query parameters are provided, the selected Prices are added to the response.

OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Product.

Query parameters:
expand
The parameter can be passed multiple times.
priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Response:
200Productasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/products/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Productjson
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 2,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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"
},
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Get Product by Key

GET
https://api.{region}.commercetools.com/{projectKey}/products/key={key}

If Price selection query parameters are provided, the selected Prices are added to the response.

OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Product.

Query parameters:
expand
The parameter can be passed multiple times.
priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Response:
200Productasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/products/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Productjson
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 2,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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"
},
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Query Products

Querying Product Attributes should not be used in high-volume use cases as it is an inefficient pattern.

We recommend using the performance-optimized Product Projection Search endpoint, which provides some functionalities that the query API lacks (including sorting by custom Attributes).

GET
https://api.{region}.commercetools.com/{projectKey}/products

If Price selection query parameters are provided, the selected Prices are added to the response.

OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where

Query Predicates on Product Attributes are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Response:
200ProductPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/products -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ProductPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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,
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
]
}

Query Product Selections for Product

Retrieves Product Selections that contain the given Product.

Query Product Selections for Product by ID

GET
https://api.{region}.commercetools.com/{projectKey}/products/{id}/product-selections
OAuth 2.0 Scopes:
view_product_selections:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Product.

Query parameters:
where
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/products/{id}/product-selections -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AssignedProductSelectionPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"results": [
{
"productSelection": {
"typeId": "product-selection",
"id": "2e89d89b-bdfb-4339-8e53-7638966a97c2"
},
"createdAt": "2022-11-21T08:56:22.150Z"
}
]
}

Check if Product exists

Check if Product exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/products/{id}

Checks if a Product exists for a given id. Returns a 200 OK status if the Product exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Product.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/products/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Product exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/products/key={key}

Checks if a Product exists for a given key. Returns a 200 OK status if the Product exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Product.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/products/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Product exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/products

Checks if a Product exists for a given Query Predicate. Returns a 200 OK status if any Products match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where

Query Predicates on Product Attributes are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/products -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Product

POST
https://api.{region}.commercetools.com/{projectKey}/products

To create a new Product, send a representation that is going to become the initial staged and current representation of the new Product in the catalog. If Price Selection query parameters are provided, selected Prices will be added to the response. Produces the ProductCreated Message.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Request Body:ProductDraftasapplication/json
Response:
201Productasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/products -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"productType" : {
"id" : "24f510c3-f334-4099-94e2-d6224a8eb919",
"typeId" : "product-type"
},
"categories" : [ {
"typeId" : "category",
"id" : "24f510c3-f334-4099-94e2-d6224a8eb919"
} ],
"name" : {
"en" : "Some Product"
},
"slug" : {
"en" : "product_slug_<random-uuid>"
},
"masterVariant" : {
"sku" : "SKU-1",
"prices" : [ {
"value" : {
"currencyCode" : "EUR",
"centAmount" : 4200
}
} ],
"images" : [ {
"url" : "http://my.custom.cdn.net/master.png",
"label" : "Master Image",
"dimensions" : {
"w" : 303,
"h" : 197
}
} ]
},
"variants" : [ {
"images" : [ {
"url" : "http://my.custom.cdn.net/variant.png",
"label" : "Variant Image",
"dimensions" : {
"w" : 303,
"h" : 197
}
} ]
} ]
}
DATA
201 Response Example: Productjson
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 2,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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"
},
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Update Product

Update Product by ID

POST
https://api.{region}.commercetools.com/{projectKey}/products/{id}

If Price selection query parameters are provided, the selected Prices are added to the response.

A failed response can return a DuplicatePriceScope, DuplicateVariantValues, DuplicateAttributeValue, or DuplicateAttributeValues error.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Product.

Query parameters:
expand
The parameter can be passed multiple times.
priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Product on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions

Update actions to be performed on the Product.

Response:
200Productasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/products/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 2,
"actions" : [ {
"action" : "setDescription",
"description" : {
"en" : "The best product ever!"
}
} ]
}
DATA
200 Response Example: Productjson
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 2,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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"
},
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Update Product by Key

POST
https://api.{region}.commercetools.com/{projectKey}/products/key={key}
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Product.

Query parameters:
expand
The parameter can be passed multiple times.
priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the Product on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions

Update actions to be performed on the Product.

Response:
200Productasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/products/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 2,
"actions" : [ {
"action" : "setDescription",
"description" : {
"en" : "The best product ever!"
}
} ]
}
DATA
200 Response Example: Productjson
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 2,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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"
},
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Update actions

Set Product Key

action
String
"setKey"
key
String

Value to set. If empty, any existing value will be removed.

Example: json
{
"action": "setKey",
"key": "DefaultKey"
}

Change Product Name

action
String
"changeName"
name

Value to set. Must not be empty.

staged
Boolean

If true, only the staged name is updated. If false, both the current and staged name are updated.

Default: true
Example: json
{
"action": "changeName",
"name": {
"de": "Mein neuer Produkt Name",
"en": "My new product name"
}
}

Set Product Description

action
String
"setDescription"
description

Value to set. If empty, any existing value will be removed.

staged
Boolean

If true, only the staged description is updated. If false, both the current and staged description are updated.

Default: true
Example: json
{
"action": "setDescription",
"description": {
"de": "Dies ist eine neue Produktbeschreibung",
"en": "This is a new product description"
}
}

Change Slug

Produces the ProductSlugChanged Message.

action
String
"changeSlug"
slug

Value to set. Must not be empty. A Product can have the same slug for different Locales, but it must be unique across the Project. Must match the pattern ^[A-Za-z0-9_-]{2,256}+$.

staged
Boolean

If true, only the staged slug is updated. If false, both the current and staged slug are updated.

Default: true
Example: json
{
"action": "changeSlug",
"slug": {
"de": "mein-neuer-produkt-slug",
"en": "my-new-product-slug"
}
}

Add ProductVariant

action
String
"addVariant"
key
String

Value to set. Must be unique.

sku
String

Value to set. Must be unique.

prices
Array of PriceDraft

Embedded Prices for the Product Variant.

MaxItems: 100
images
Array of Image

Images for the Product Variant.

attributes
Array of Attribute

Attributes for the Product Variant.

staged
Boolean

If true the new Product Variant is only staged. If false the new Product Variant is both current and staged.

Default: true
assets
Array of AssetDraft

Media assets for the Product Variant.

Example: json
{
"action": "addVariant",
"key": "VariantKey",
"sku": "VariantSKU"
}

Remove ProductVariant

Either id or sku is required. Produces the ProductVariantDeleted Message. If the Product Variant to remove is part of a ProductSelectionAssignment its SKU will be automatically removed from the respective ProductVariantSelection.

id
Int

The id of the ProductVariant to remove.

action
String
"removeVariant"
sku
String

The sku of the ProductVariant to remove.

staged
Boolean

If true, only the staged ProductVariant is removed. If false, both the current and staged ProductVariant is removed.

Default: true
Example: json
{
"action": "removeVariant",
"id": 2
}

Change Master Variant

Assigns the specified Product Variant to the masterVariant and removes the same from variants at the same time. The current Master Variant becomes part of the variants array. Either variantId or sku is required.

action
String
"changeMasterVariant"
variantId
Int

The id of the ProductVariant to become the Master Variant.

sku
String

The sku of the ProductVariant to become the Master Variant.

staged
Boolean

If true, only the staged Master Variant is changed. If false, both the current and staged Master Variant are changed.

Default: true
Example: json
{
"action": "changeMasterVariant",
"variantId": 1
}

Set PriceMode

Controls whether the Prices of a Product Variant are embedded into the Product or standalone.

action
String
"setPriceMode"
priceMode

Specifies which type of Prices should be used when looking up a price for the Product.

Default: Embedded
Example: json
{
"action": "setPriceMode",
"priceMode": "Standalone"
}

Add Price

Adds the given Price to the prices array of the ProductVariant. Either variantId or sku is required.

action
String
"addPrice"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

price

Embedded Price to add to the Product Variant.

staged
Boolean

If true, only the staged prices is updated. If false, both the current and staged prices are updated.

Default: true
Example: json
{
"action": "addPrice",
"variantId": 1,
"price": {
"value": {
"currencyCode": "EUR",
"centAmount": 4000
}
}
}

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 an Embedded Price is rejected:

  • if the product already contains an Embedded Price with the same price scope (same currency, country, customer group, channel, valid from and valid until).
  • if two Embedded 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. If your business case requires going beyond this limit, use StandalonePrices instead.

Nonetheless, to keep the number of Embedded 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.

Set Prices

Either variantId or sku is required.

action
String
"setPrices"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

prices
Array of PriceDraft

The Embedded Prices to set. Each Price must have its unique Price scope (with same currency, country, Customer Group, Channel, validFrom and validUntil).

staged
Boolean

If true, only the staged ProductVariant is updated. If false, both the current and staged ProductVariant are updated.

Default: true
Example: json
{
"action": "setPrices",
"variantId": 1,
"prices": [
{
"value": {
"currencyCode": "USD",
"centAmount": 3100
}
},
{
"value": {
"currencyCode": "EUR",
"centAmount": 4000
}
}
]
}

Change Price

action
String
"changePrice"
priceId
String

The id of the Embedded Price to update.

price

Value to set.

staged
Boolean

If true, only the staged Embedded Price is updated. If false, both the current and staged Embedded Price are updated.

Default: true
Example: json
{
"action": "changePrice",
"priceId": "{{priceId}}",
"price": {
"value": {
"currencyCode": "EUR",
"centAmount": 4000
}
},
"staged": true
}

Remove Price

action
String
"removePrice"
priceId
String

The id of the Embedded Price to remove.

staged
Boolean

If true, only the staged Embedded Price is removed. If false, both the current and staged Embedded Price are removed.

Default: true
Example: json
{
"action": "removePrice",
"priceId": "{{priceId}}"
}

Set Price Custom Type

action
String
"setProductPriceCustomType"
priceId
String

The id of the Embedded Price to update.

staged
Boolean

If true, only the staged Embedded Price is updated. If false, both the current and staged Embedded Price is updated.

Default: true

Defines the Type that extends the Price with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Embedded Price.

fields

Sets the Custom Fields fields for the Embedded Price.

Example: json
{
"action": "setProductPriceCustomType",
"priceId": "{{priceId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Price CustomField

action
String
"setProductPriceCustomField"
priceId
String

The id of the Embedded Price to update.

staged
Boolean

If true, only the staged Embedded Price Custom Field is updated. If false, both the current and staged Embedded Price Custom Field are updated.

Default: true
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setProductPriceCustomField",
"priceId": "{{priceId}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Set Discounted Price

Produces the ProductPriceExternalDiscountSet Message.

action
String
"setDiscountedPrice"
priceId
String

The id of the Price to set the Discount.

staged
Boolean

If true, only the staged Embedded Price is updated. If false, both the current and staged Embedded Price are updated.

Default: true
discounted

Value to set. If empty, any existing value will be removed. The referenced ProductDiscount must have the Type external, be active, and its predicate must match the referenced Price.

Example: json
{
"action": "setDiscountedPrice",
"priceId": "{{priceId}}",
"staged": true,
"discounted": {
"value": {
"currencyCode": "EUR",
"centAmount": 4000
},
"discount": {
"typeId": "product-discount",
"id": "{{product-discount-id}}"
}
}
}

Set Price Key

Sets the key of an Embedded Price. Produces the ProductPriceKeySet Message.

action
String
"setPriceKey"
key
String

Value to set. If empty, any existing value will be removed.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
priceId
String

The id of the Price to set the key.

staged
Boolean

If true, only the staged Embedded Price is updated. If false, both the current and staged Embedded Price are updated.

Default: true
Example: json
{
"action": "setPriceKey",
"priceId": "{{priceId}}",
"key": "a-new-embedded-price-key",
"staged": true
}

Set Attribute

Either variantId or sku is required.

action
String
"setAttribute"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

name
String

The name of the Attribute to set.

value
Any

Value to set for the Attribute. If empty, any existing value will be removed.

The AttributeType determines the format of the Attribute value to be provided:

staged
Boolean

If true, only the staged Attribute is set. If false, both current and staged Attribute is set.

Default: true
Example: json
{
"action": "setAttribute",
"variantId": 1,
"name": "ExampleStringTypeAttribute",
"value": "TextString"
}

Set Attribute In All Variants

Adds, removes, or changes a Product Attribute in all Product Variants at the same time. This action is useful for setting values for Attributes with the Constraint SameForAll.

action
String
"setAttributeInAllVariants"
name
String

The name of the Attribute to set.

value
Any

Value to set for the Attributes. If empty, any existing value will be removed.

The AttributeType determines the format of the Attribute value to be provided:

staged
Boolean

If true, only the staged Attributes are set. If false, both the current and staged Attributes are set.

Default: true
Example: json
{
"action": "setAttributeInAllVariants",
"name": "ExampleStringTypeAttribute",
"value": "TextString"
}

Add to Category

Produces the ProductAddedToCategory Message.

action
String
"addToCategory"

The Category to add.

orderHint
String

A string representing a number between 0 and 1. Must start with 0. and cannot end with 0. If empty, any existing value will be removed.

Pattern: ^0.[0-9]*[1-9]$
staged
Boolean

If true, only the staged categories and categoryOrderHints are updated. If false, both the current and staged categories and categoryOrderHints are updated.

Default: true
Example: json
{
"action": "addToCategory",
"category": {
"typeId": "category",
"id": "{{category-id}}"
}
}

Set Category Order Hint

action
String
"setCategoryOrderHint"
categoryId
String

The id of the Category to add the orderHint.

orderHint
String

A string representing a number between 0 and 1. Must start with 0. and cannot end with 0. If empty, any existing value will be removed.

Pattern: ^0.[0-9]*[1-9]$
staged
Boolean

If true, only the staged categoryOrderHints is updated. If false, both the current and staged categoryOrderHints are updated.

Default: true
Example: json
{
"action": "setCategoryOrderHint",
"categoryId": "{{category-id}}",
"orderHint": "0.1"
}

Remove from Category

Produces the ProductRemovedFromCategory Message.

action
String
"removeFromCategory"

The Category to remove.

staged
Boolean

If true, only the staged categories and categoryOrderHints are removed. If false, both the current and staged categories and categoryOrderHints are removed.

Default: true
Example: json
{
"action": "removeFromCategory",
"category": {
"typeId": "category",
"id": "{{category-id}}"
}
}

Set TaxCategory

Cannot be staged. Published Products are immediately updated.

action
String
"setTaxCategory"

The Tax Category to set. If empty, any existing value will be removed.

Example: json
{
"action": "setTaxCategory",
"taxCategory": {
"typeId": "tax-category",
"id": "{{tax-category-id}}"
}
}

Set SKU

SKU cannot be changed or removed if it is associated with an InventoryEntry. If the SKU to set or unset is part of a ProductSelectionAssignment it will be automatically added or removed from the respective ProductVariantSelection.

action
String
"setSku"
variantId
Int

The id of the ProductVariant to update.

sku
String

Value to set. Must be unique. If empty, any existing value will be removed.

staged
Boolean

If true, only the staged sku is updated. If false, both the current and staged sku are updated.

Default: true
Example: json
{
"action": "setSku",
"variantId": 1,
"sku": "SKU"
}

Set ProductVariant Key

Either variantId or sku is required.

action
String
"setProductVariantKey"
key
String

Value to set. Must be unique. If empty, any existing value will be removed.

variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged key is set. If false, both the current and staged key are set.

Default: true
Example: json
{
"action": "setProductVariantKey",
"variantId": 1,
"key": "keyString"
}

Add External Image

Either variantId or sku is required. Produces the ProductImageAdded Message.

action
String
"addExternalImage"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

image

Value to add to images.

staged
Boolean

If true, only the staged images is updated. If false, both the current and staged images is updated.

Default: true
Example: json
{
"action": "addExternalImage",
"variantId": 1,
"image": {
"url": "//myimage.jpg",
"dimensions": {
"w": 1400,
"h": 1400
},
"label": "myImage"
}
}

Move Image To Position

Either variantId or sku is required.

action
String
"moveImageToPosition"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

imageUrl
String

The URL of the image to update.

position
Int

Position in images where the image should be moved. Must be between 0 and the total number of images minus 1.

staged
Boolean

If true, only the staged images is updated. If false, both the current and staged images is updated.

Default: true
Example: json
{
"action": "moveImageToPosition",
"variantId": 1,
"imageUrl": "//myimage2.jpg",
"position": 1
}

Remove Image

Removes a Product image and deletes it from the Content Delivery Network (external images are not deleted). Deletion from the CDN is not instant, which means the image file itself will stay available for some time after the deletion. Either variantId or sku is required.

action
String
"removeImage"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

imageUrl
String

The URL of the image to remove.

staged
Boolean

If true, only the staged image is removed. If false, both the current and staged image is removed.

Default: true
Example: json
{
"action": "removeImage",
"variantId": 1,
"imageUrl": "//myimage2.jpg"
}

Set Image Label

Either variantId or sku is required.

action
String
"setImageLabel"
sku
String

The sku of the ProductVariant to update.

variantId
Int

The id of the ProductVariant to update.

imageUrl
String

The URL of the image to set the label.

label
String

Value to set. If empty, any existing value will be removed.

staged
Boolean

If true, only the staged image is updated. If false, both the current and staged image is updated.

Default: true
Example: json
{
"action": "setImageLabel",
"variantId": 2,
"imageUrl": "//image.png",
"label": "labelString",
"staged": true
}

Add Asset

Either variantId or sku is required.

action
String
"addAsset"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged assets are updated. If false, both the current and staged assets are updated.

Default: true
asset

Value to append.

position
Int

Position in assets where the Asset should be put. When specified, the value must be between 0 and the total number of Assets minus 1.

Example: json
{
"action": "addAsset",
"variantId": 1,
"asset": {
"sources": [
{
"uri": "//asset.mp4"
}
],
"name": {
"de": "FirstAssetDE",
"en": "FirstassetEN"
}
}
}

Remove Asset

Either variantId or sku is required. The Asset to remove must be specified using either assetId or assetKey.

action
String
"removeAsset"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged Asset is removed. If false, both the current and staged Asset is removed.

Default: true
assetId
String

The id of the Asset to remove.

assetKey
String

The key of the Asset to remove.

Example: json
{
"action": "removeAsset",
"variantId": 1,
"assetId": "{{assetId}}"
}

Set Asset Key

Either variantId or sku is required.

action
String
"setAssetKey"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.

Default: true
assetId
String

The id of the Asset to update.

assetKey
String

Value to set. If empty, any existing value will be removed.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
Example: json
{
"action": "setAssetKey",
"variantId": 1,
"assetId": "{{assetId}}",
"assetKey": "assetKeyString"
}

Change Asset Order

Either variantId or sku is required.

action
String
"changeAssetOrder"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged assets is updated. If false, both the current and staged assets are updated.

Default: true
assetOrder
Array of String

All existing Asset ids of the ProductVariant in the desired new order.

Example: json
{
"action": "changeAssetOrder",
"variantId": 1,
"assetOrder": ["{{assetId1}}", "{{assetId2}}"]
}

Change Asset Name

Either variantId or sku is required. The Asset to update must be specified using either assetId or assetKey.

action
String
"changeAssetName"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.

Default: true
assetId
String

The id of the Asset to update.

assetKey
String

The key of the Asset to update.

name

New value to set. Must not be empty.

Example: json
{
"action": "changeAssetName",
"variantId": 1,
"assetId": "{{assetId}}",
"name": {
"de": "Mein Asset",
"en": "My asset"
}
}

Set Asset Description

Either variantId or sku is required. The Asset to update must be specified using either assetId or assetKey.

action
String
"setAssetDescription"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.

Default: true
assetId
String

The id of the Asset to update.

assetKey
String

The key of the Asset to update.

description

Value to set. If empty, any existing value will be removed.

Example: json
{
"action": "setAssetDescription",
"variantId": 1,
"assetId": "{{assetId}}",
"description": {
"de": "Dies ist eine Asset-Beschreibung",
"en": "This is an asset description"
}
}

Set Asset Tags

Either variantId or sku is required. The Asset to update must be specified using either assetId or assetKey.

action
String
"setAssetTags"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.

Default: true
assetId
String

The id of the Asset to update.

assetKey
String

The key of the Asset to update.

tags
Array of String

Keywords for categorizing and organizing Assets.

Example: json
{
"action": "setAssetTags",
"variantId": 1,
"assetId": "{{assetId}}",
"tags": ["commercetools", "awesome"]
}

Set Asset Sources

Either variantId or sku is required. The Asset to update must be specified using either assetId or assetKey.

action
String
"setAssetSources"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged Asset is updated. If false both the current and staged Asset is updated.

Default: true
assetId
String

The id of the Asset to update.

assetKey
String

The key of the Asset to update.

sources
Array of AssetSource

Value to set.

MinItems: 1
Example: json
{
"action": "setAssetSources",
"variantId": 1,
"assetId": "{{assetId}}",
"sources": [
{
"uri": "https://www.commercetools.de/ct-logo.svg",
"key": "vector"
}
]
}

Set Asset Custom Type

Either variantId or sku is required. The Asset to update must be specified using either assetId or assetKey.

action
String
"setAssetCustomType"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.

Default: true
assetId
String

The id of the Asset to update.

assetKey
String

The key of the Asset to update.

Defines the Type that extends the Asset with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Asset.

fields

Sets the Custom Fields fields for the Asset.

Example: json
{
"action": "setAssetCustomType",
"variantId": 1,
"assetId": "{{assetId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set Asset CustomField

Either variantId or sku is required. The Asset to update must be specified using either assetId or assetKey.

action
String
"setAssetCustomField"
variantId
Int

The id of the ProductVariant to update.

sku
String

The sku of the ProductVariant to update.

staged
Boolean

If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.

Default: true
assetId
String

The id of the Asset to update.

assetKey
String

The key of the Asset to update.

name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setAssetCustomField",
"variantId": 1,
"assetId": "{{assetId}}",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Set SearchKeywords

action
String
"setSearchKeywords"
searchKeywords

Value to set.

staged
Boolean

If true, only the staged searchKeywords is updated. If false, both the current and staged searchKeywords are updated.

Default: true
Example: json
{
"action": "setSearchKeywords",
"searchKeywords": {
"en": [
{
"text": "Super Keyword"
},
{
"text": "What a keyword",
"suggestTokenizer": {
"type": "whitespace"
}
}
],
"de": [
{
"text": "Ein super Schlüsselwort",
"suggestTokenizer": {
"type": "custom",
"inputs": ["wow wow wow", "super genial", "der Wahnsinn"]
}
}
]
}
}

Set Meta Title

action
String
"setMetaTitle"
metaTitle

Value to set. If empty, any existing value will be removed.

staged
Boolean

If true, only the staged metaTitle is updated. If false, both the current and staged metaTitle are updated.

Default: true
Example: json
{
"action": "setMetaTitle",
"metaTitle": {
"de": "mein MetaTitel",
"en": "my metaTitle"
}
}

Set Meta Description

action
String
"setMetaDescription"
metaDescription

Value to set. If empty, any existing value will be removed.

staged
Boolean

If true, only the staged metaDescription is updated. If false, both the current and staged metaDescription are updated.

Default: true
Example: json
{
"action": "setMetaDescription",
"metaDescription": {
"de": "meine Meta Beschreibung",
"en": "my metaDescription"
}
}

Set Meta Keywords

action
String
"setMetaKeywords"
metaKeywords

Value to set. If empty, any existing value will be removed.

staged
Boolean

If true, only the staged metaKeywords is updated. If false, both the current and staged metaKeywords are updated.

Default: true
Example: json
{
"action": "setMetaKeywords",
"metaKeywords": {
"de": "mein MetaKeyword",
"en": "my metaKeeyword"
}
}

Revert Staged Changes

Reverts the staged version of a Product to the current version. Produces the ProductRevertedStagedChanges Message.

action
String
"revertStagedChanges"
Example: json
{
"action": "revertStagedChanges"
}

Revert Staged Variant Changes

Reverts the staged version of a ProductVariant to the current version.

action
String
"revertStagedVariantChanges"
variantId
Int

The id of the ProductVariant to revert.

Example: json
{
"action": "revertStagedVariantChanges",
"variantId": 2
}

Publish

Publishes product data from the Product's staged projection to its current projection. Produces the ProductPublished Message.

action
String
"publish"

All or Prices

Example: json
{
"action": "publish"
}

ProductPublishScope

The scope controls which part of the product information is published.

All

Publishes a Product that 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. This is the default scope.

Prices

Publishes the Prices of the Product (only if the Product is already published). All Product Variants' Prices in the staged projection are published into the current projection with the same id. Prices in a staged Product Variant that has no current projection are not published. Prices in a current Product Variant that has no staged projection are unchanged. The hasStagedChanges flag is updated according to whether the staged and current projections still differ after the prices are published.

Unpublish

Removes the current projection of the Product. The staged projection is unaffected. To retrieve unpublished Products, the staged parameter must be set to false when querying/searching Product Projections. Produces the ProductUnpublished Message.

Unpublished Products cannot be added to a Cart. However, if a Cart contains Line Items for Products that were added before the Product was unpublished, the Cart is unaffected and can still be used to create an Order. To prevent this, in addition to unpublishing the Product you should remove the Prices from the Product using Remove Price for Embedded Prices or Delete StandalonePrice for Standalone Prices.

action
String
"unpublish"
Example: json
{
"action": "unpublish"
}

Transition State

If the existing State has set transitions, there must be a direct transition to the new State. If transitions is not set, no validation is performed. Produces the ProductStateTransition Message.

action
String
"transitionState"

The State to transition to. If there is no existing State, this must be an initial State.

force
Boolean

If true, validations are disabled.

Default: false
Example: json
{
"action": "transitionState",
"state": {
"typeId": "state",
"id": "{{state-id}}"
}
}

Upload Product image

Uploads a binary image file to a given ProductVariant. After upload, the system converts the original image to several sizes that are available on the builtin Content Delivery Network (CDN). Supported image formats are JPEG, PNG, and GIF. The maximum file size of the image to upload is 10 MB.

Only images in sRGB color space are supported. When trying to upload images with other color spaces, like Adobe RGB, the API returns a 400 Bad Request Error with code InvalidInput and the message Unsupported image data. Not able to identify the color model of your image.

A 200 OK response with a Product is returned once the Small version of the image has been uploaded to the CDN. Other sizes may not be available immediately after a response is returned, but soon after. Produces the ProductImageAdded Message once the Small version of the image has been uploaded to the CDN.

The Image uploaded to the CDN is publicly available and its url may be shared across different Products in the same Project or in other Projects. However, the Image itself is tied to the Product Variant where it was originally uploaded. If this Product Variant is deleted, or if the Image is removed from the Product Variant, the Image will be deleted from the CDN, and will no longer be available at its original URL.

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 or sku is required to update a specific ProductVariant. The image is uploaded to the Master Variant if variant or sku are not provided.

  • variant - String - Optional
    The id of the ProductVariant the image should be uploaded to.
  • sku - String - Optional
    The sku of the ProductVariant the image should be uploaded to.
  • filename - String - Optional (Defaults to "img")
    URL-encoded filename of the image when stored in the Content Delivery Network (CDN). The filename is modified when uploaded to prevent filename conflicts. If not provided, a random filename is generated.
  • staged - Boolean - Optional (Defaults to true)
    If true, only the staged ProductVariant is updated. If false, both the current and staged ProductVariant are updated.

Body: The raw binary data.

The cURL example below adds an Image to the ProductVariant with id = 2, in the staged projection of the Product specified in path parameter {id}:

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"

As the filename parameter was included (filename=detail.jpg), an example URL of the uploaded image is https://{commercetools-cdn}/detail-6xAq4Efp.jpg.

File upload using Content-Type: multipart/form-data is currently not supported.

Delete Product

Published Products cannot be deleted. Unpublish those before you delete them.

Delete Product by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/products/{id}

If Price selection query parameters are provided, the selected Prices are added to the response. Produces the ProductDeleted Message.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Product.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Response:
200Productasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/products/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Productjson
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 2,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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"
},
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Delete Product by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/products/key={key}

If Price selection query parameters are provided, the selected Prices are added to the response. Produces the ProductDeleted Message.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Product.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
priceCurrency

The currency used for Price selection.

priceCountry

The country used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Used for locale-based projection.

The parameter can be passed multiple times.
Response:
200Productasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/products/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Productjson
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 2,
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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://commercetools.com/cli/data/253245821_1.jpg"
}
],
"prices": [
{
"value": {
"type": "centPrecision",
"fractionDigits": 2,
"centAmount": 10000,
"currencyCode": "EUR"
},
"id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
}
],
"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"
},
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}