Products represent the sellable goods in a commerce project.
Representations
Product
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 DateTime | Date and time (UTC) the Product was initially created. |
createdBy BETA | IDs and references that created the Product. |
lastModifiedAt DateTime | Date and time (UTC) the Product was last updated. |
lastModifiedBy BETA | IDs and references that last modified the Product. |
warnings Array of WarningObject | Warnings about processing of a request.
Appears in response to requests with response status code 202 Accepted . |
{
"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. This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing Products with the Import API and the Merchant Center.
To update a Product using the Import API or Merchant Center, the Product key must match the pattern ^[A-Za-z0-9_-]{2,256}$ . |
productType | 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 Array of CategoryResourceIdentifier | Categories assigned to the Product. |
categoryOrderHints | Numerical values to allow ordering of Products within a specified Category. |
metaTitle | Title of the Product as used by search engines. |
metaDescription | Description of the Product as used by search engines. |
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 Array of ProductVariantDraft | The additional Product Variants for the Product. MaxItems:100 |
taxCategory | The Tax Category to be assigned to the Product. |
searchKeywords | Used by Product Suggestions, but is also considered for a full text search. |
state | State to be assigned to the Product. |
publish Boolean | If true , the Product is published immediately to the current projection. |
priceMode | Specifies the type of prices used when looking up a price for the Product. Default:Embedded |
{
"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
limit Int | Number of results requested. Default: 20 Minimum: 0 Maximum: 500 |
offset Int | Number of elements skipped. Default: 0 Maximum: 10000 |
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 | product Type of referenced resource. |
obj | Contains the representation of the expanded Product. Only present in responses to requests with Reference Expansion for Products. |
ProductResourceIdentifier
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 | product Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
ProductCatalogData
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 as used by search engines. |
metaDescription | Description of the Product as used by search engines. |
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. MaxItems:100 |
searchKeywords | Used by Product Suggestions, but is also considered for a full text search. |
CategoryOrderHints
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 parameter matching this regular expression | A string representing a number between 0 and 1 that must start with 0. and cannot end with 0 . |
{
"categoryOrderHints": {
"7bcd33e6-c1c7-4b96-8d70-9b9b18b19b70": "0.992"
}
}
SearchKeywords
{
"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 SuggestionResult. |
suggestTokenizer | If no tokenizer is defined, the text is used as a single token. |
SuggestTokenizer
type
field.Whitespace Tokenizer
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, MaxItems: validFrom and validUntil ).100 |
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 Product price selection.
Can be used to sort, filter, and facet. |
scopedPriceDiscounted Boolean | Only available in response to a Product Projection Search request
with Product price selection. |
ProductVariantDraft
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, MaxItems: validFrom and validUntil ).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
value
field: "value" : "\"A value\""
.name String | Name of the Attribute. (elementIdentifier):true |
value Any | The AttributeType determines the format of the Attribute
value to be provided:
true |
Image
url String | URL of the image in its original size that must be unique within a single ProductVariant. |
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:
-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
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
channels
is returned. If not, then isOnStock
, restockableInDays
, and availableQuantity
are returned.id String | Unique identifier of the InventoryEntry. |
version Int | Current version of the InventoryEntry. |
channels | 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
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
Embedded
Standalone
- Composable Commerce uses StandalonePrices, which are associated with the ProductVariant through the
sku
field.
ScopedPrice
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 DateTime | Date and time from which the Price is valid. |
validUntil DateTime | 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
view_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the Product. |
expand | The parameter can be passed multiple times. |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | Enables Product price selection and Scoped Price Search.
It can be used only in conjunction with the priceCurrency parameter.Pattern: ^[A-Z]{2}$ |
priceCustomerGroup String | id of an existing CustomerGroup used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
priceCustomerGroupAssignments String | IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups.
It can be used only in conjunction with the priceCurrency parameter.The parameter can be passed multiple times. |
priceChannel String | id of an existing Channel used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/products/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
view_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the Product. |
expand | The parameter can be passed multiple times. |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | Enables Product price selection and Scoped Price Search.
It can be used only in conjunction with the priceCurrency parameter.Pattern: ^[A-Z]{2}$ |
priceCustomerGroup String | id of an existing CustomerGroup used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
priceCustomerGroupAssignments String | IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups.
It can be used only in conjunction with the priceCurrency parameter.The parameter can be passed multiple times. |
priceChannel String | id of an existing Channel used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/products/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
view_products:{projectKey}
view_published_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
where | |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int | Number of results requested. Default: 20 Minimum: 0 Maximum: 500 |
offset Int | Number of elements skipped. Default: 0 Maximum: 10000 |
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.Default: true |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | Enables Product price selection and Scoped Price Search.
It can be used only in conjunction with the priceCurrency parameter.Pattern: ^[A-Z]{2}$ |
priceCustomerGroup String | id of an existing CustomerGroup used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
priceCustomerGroupAssignments String | IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups.
It can be used only in conjunction with the priceCurrency parameter.The parameter can be passed multiple times. |
priceChannel String | id of an existing Channel used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
var.<varName> String | Predicate parameter values. The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/products -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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.
by Product ID
view_product_selections:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the Product. |
where | 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 | Number of results requested. Default: 20 Minimum: 0 Maximum: 500 |
offset Int | Number of elements skipped. Default: 0 Maximum: 10000 |
withTotal Boolean | |
var.<varName> String | Predicate parameter values. The parameter can be passed multiple times. |
AssignedProductSelectionPagedQueryResponse
asapplication/json
curl --get https://api.{region}.commercetools.com/{projectKey}/products/{id}/product-selections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 1,
"results": [
{
"productSelection": {
"typeId": "product-selection",
"id": "2e89d89b-bdfb-4339-8e53-7638966a97c2"
},
"createdAt": "2022-11-21T08:56:22.150Z"
}
]
}
by Product Key
view_product_selections:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the Product. |
where | 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 | Number of results requested. Default: 20 Minimum: 0 Maximum: 500 |
offset Int | Number of elements skipped. Default: 0 Maximum: 10000 |
withTotal Boolean | |
var.<varName> String | Predicate parameter values. The parameter can be passed multiple times. |
AssignedProductSelectionPagedQueryResponse
asapplication/json
curl --get https://api.{region}.commercetools.com/{projectKey}/products/key={key}/product-selections -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
id
. Returns a 200 OK
status if the Product exists or a 404 Not Found
otherwise.view_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the Product. |
curl --head https://api.{region}.commercetools.com/{projectKey}/products/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Product exists by Key
key
. Returns a 200 OK
status if the Product exists or a 404 Not Found
otherwise.view_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the Product. |
curl --head https://api.{region}.commercetools.com/{projectKey}/products/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Product exists by Query Predicate
200 OK
status if any Products match the query predicate, or a 404 Not Found
otherwise.view_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/products -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create Product
manage_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
expand | The parameter can be passed multiple times. |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | Enables Product price selection and Scoped Price Search.
It can be used only in conjunction with the priceCurrency parameter.Pattern: ^[A-Z]{2}$ |
priceCustomerGroup String | id of an existing CustomerGroup used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
priceCustomerGroupAssignments String | IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups.
It can be used only in conjunction with the priceCurrency parameter.The parameter can be passed multiple times. |
priceChannel String | id of an existing Channel used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
application/json
application/json
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
{
"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
manage_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the Product. |
expand | The parameter can be passed multiple times. |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | Enables Product price selection and Scoped Price Search.
It can be used only in conjunction with the priceCurrency parameter.Pattern: ^[A-Z]{2}$ |
priceCustomerGroup String | id of an existing CustomerGroup used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
priceCustomerGroupAssignments String | IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups.
It can be used only in conjunction with the priceCurrency parameter.The parameter can be passed multiple times. |
priceChannel String | id of an existing Channel used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
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 Array of ProductUpdateAction | Update actions to be performed on the Product. |
application/json
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
{
"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
manage_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the Product. |
expand | The parameter can be passed multiple times. |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | Enables Product price selection and Scoped Price Search.
It can be used only in conjunction with the priceCurrency parameter.Pattern: ^[A-Z]{2}$ |
priceCustomerGroup String | id of an existing CustomerGroup used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
priceCustomerGroupAssignments String | IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups.
It can be used only in conjunction with the priceCurrency parameter.The parameter can be passed multiple times. |
priceChannel String | id of an existing Channel used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
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 Array of ProductUpdateAction | Update actions to be performed on the Product. |
application/json
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
{
"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. To update a Product using the Import API and the Merchant Center, the Product key must match the pattern ^[A-Za-z0-9_-]{2,256}$ . |
{
"action": "setKey",
"key": "DefaultKey"
}
Change Product Name
action String | "changeName" |
name | Value to set. Must not be empty. |
staged Boolean | If Default: true , only the staged name is updated. If false , both the current and staged name are updated.true |
{
"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 Default: true , only the staged description is updated. If false , both the current and staged description are updated.true |
{
"action": "setDescription",
"description": {
"de": "Dies ist eine neue Produktbeschreibung",
"en": "This is a new product description"
}
}
Change Slug
action String | "changeSlug" |
slug | |
staged Boolean | If Default: true , only the staged slug is updated. If false , both the current and staged slug are updated.true |
{
"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 Default: true the new Product Variant is only staged. If false the new Product Variant is both current and staged.true |
assets Array of AssetDraft | Media assets for the Product Variant. |
{
"action": "addVariant",
"key": "VariantKey",
"sku": "VariantSKU"
}
Remove ProductVariant
images
that have been uploaded to our CDN and that are also used on other Product Variants, then removing the Product Variant will make the images unavailable wherever they are shared.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 Default: true , only the staged ProductVariant is removed. If false , both the current and staged ProductVariant is removed.true |
{
"action": "removeVariant",
"id": 2
}
Change Master Variant
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 Default: true , only the staged Master Variant is changed. If false , both the current and staged Master Variant are changed.true |
{
"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 |
{
"action": "setPriceMode",
"priceMode": "Standalone"
}
Add Price
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 Default: true , only the staged prices is updated. If false , both the current and staged prices are updated.true |
{
"action": "addPrice",
"variantId": 1,
"price": {
"value": {
"currencyCode": "EUR",
"centAmount": 4000
}
}
}
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.
100
prices can be specified on a ProductVariant. If your business case requires going beyond this limit, use StandalonePrices instead.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
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, MaxItems: validFrom and validUntil ).100 |
staged Boolean | If Default: true , only the staged ProductVariant is updated. If false , both the current and staged ProductVariant are updated.true |
{
"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 Default: true , only the staged Embedded Price is updated. If false , both the current and staged Embedded Price are updated.true |
{
"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 Default: true , only the staged Embedded Price is removed. If false , both the current and staged Embedded Price are removed.true |
{
"action": "removePrice",
"priceId": "{{priceId}}"
}
Set Price Custom Type
action String | "setProductPriceCustomType" |
priceId String | The id of the Embedded Price to update. |
staged Boolean | If Default: true , only the staged Embedded Price is updated. If false , both the current and staged Embedded Price is updated.true |
type | 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. |
{
"action": "setProductPriceCustomType",
"priceId": "{{priceId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}
Set Price CustomField
action String | "setProductPriceCustomField" |
priceId String | The id of the Embedded Price to update. |
staged Boolean | If Default: true , only the staged Embedded Price Custom Field is updated. If false , both the current and staged Embedded Price Custom Field are updated.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 . |
{
"action": "setProductPriceCustomField",
"priceId": "{{priceId}}",
"name": "exampleStringField",
"value": "TextString"
}
Set Discounted Price
action String | "setDiscountedPrice" |
priceId String | The id of the Price to set the Discount. |
staged Boolean | If Default: true , only the staged Embedded Price is updated. If false , both the current and staged Embedded Price are updated.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. |
{
"action": "setDiscountedPrice",
"priceId": "{{priceId}}",
"staged": true,
"discounted": {
"value": {
"currencyCode": "EUR",
"centAmount": 4000
},
"discount": {
"typeId": "product-discount",
"id": "{{product-discount-id}}"
}
}
}
Set Price Key
action String | "setPriceKey" |
key String | Value to set. If empty, any existing value will be removed. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
priceId String | The id of the Price to set the key. |
staged Boolean | If Default: true , only the staged Embedded Price is updated. If false , both the current and staged Embedded Price are updated.true |
{
"action": "setPriceKey",
"priceId": "{{priceId}}",
"key": "a-new-embedded-price-key",
"staged": true
}
Set Attribute
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 Default: true , only the staged Attribute is set. If false , both current and staged Attribute is set.true |
{
"action": "setAttribute",
"variantId": 1,
"name": "ExampleStringTypeAttribute",
"value": "TextString"
}
Set Attribute In All Variants
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 Default: true , only the staged Attributes are set. If false , both the current and staged Attributes are set.true |
{
"action": "setAttributeInAllVariants",
"name": "ExampleStringTypeAttribute",
"value": "TextString"
}
Add to Category
action String | "addToCategory" |
category | The Category to add. |
orderHint String | A string representing a number between 0 and 1. Must start with Pattern: 0. and cannot end with 0 . If empty, any existing value will be removed.^0.[0-9]*[1-9]$ |
staged Boolean | If Default: true , only the staged categories and categoryOrderHints are updated. If false , both the current and staged categories and categoryOrderHints are updated.true |
{
"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 Pattern: 0. and cannot end with 0 . If empty, any existing value will be removed.^0.[0-9]*[1-9]$ |
staged Boolean | If Default: true , only the staged categoryOrderHints is updated. If false , both the current and staged categoryOrderHints are updated.true |
{
"action": "setCategoryOrderHint",
"categoryId": "{{category-id}}",
"orderHint": "0.1"
}
Remove from Category
action String | "removeFromCategory" |
category | The Category to remove. |
staged Boolean | If Default: true , only the staged categories and categoryOrderHints are removed. If false , both the current and staged categories and categoryOrderHints are removed.true |
{
"action": "removeFromCategory",
"category": {
"typeId": "category",
"id": "{{category-id}}"
}
}
Set TaxCategory
Cannot be staged. Published Products are immediately updated.
action String | "setTaxCategory" |
taxCategory | The Tax Category to set. If empty, any existing value will be removed. |
{
"action": "setTaxCategory",
"taxCategory": {
"typeId": "tax-category",
"id": "{{tax-category-id}}"
}
}
Set SKU
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 Default: true , only the staged sku is updated. If false , both the current and staged sku are updated.true |
{
"action": "setSku",
"variantId": 1,
"sku": "SKU"
}
Set ProductVariant Key
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 Default: true , only the staged key is set. If false , both the current and staged key are set.true |
{
"action": "setProductVariantKey",
"variantId": 1,
"key": "keyString"
}
Add External Image
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 Default: true , only the staged images is updated. If false , both the current and staged images is updated.true |
{
"action": "addExternalImage",
"variantId": 1,
"image": {
"url": "//myimage.jpg",
"dimensions": {
"w": 1400,
"h": 1400
},
"label": "myImage"
}
}
Move Image To Position
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 Default: true , only the staged images is updated. If false , both the current and staged images is updated.true |
{
"action": "moveImageToPosition",
"variantId": 1,
"imageUrl": "//myimage2.jpg",
"position": 1
}
Remove Image
url
is also used on other Product Variants, then removing the image will make it unavailable wherever it is shared.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 Default: true , only the staged image is removed. If false , both the current and staged image is removed.true |
{
"action": "removeImage",
"variantId": 1,
"imageUrl": "//myimage2.jpg"
}
Set Image Label
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 Default: true , only the staged image is updated. If false , both the current and staged image is updated.true |
{
"action": "setImageLabel",
"variantId": 2,
"imageUrl": "//image.png",
"label": "labelString",
"staged": true
}
Add Asset
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 Default: true , only the staged assets are updated. If false , both the current and staged assets are updated.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 . |
{
"action": "addAsset",
"variantId": 1,
"asset": {
"sources": [
{
"uri": "//asset.mp4"
}
],
"name": {
"de": "FirstAssetDE",
"en": "FirstassetEN"
}
}
}
Remove Asset
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 Default: true , only the staged Asset is removed. If false , both the current and staged Asset is removed.true |
assetId String | The id of the Asset to remove. |
assetKey String | The key of the Asset to remove. |
{
"action": "removeAsset",
"variantId": 1,
"assetId": "{{assetId}}"
}
Set Asset Key
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 Default: true , only the staged Asset is updated. If false , both the current and staged Asset is updated.true |
assetId String | The id of the Asset to update. |
assetKey String | Value to set. If empty, any existing value will be removed. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
{
"action": "setAssetKey",
"variantId": 1,
"assetId": "{{assetId}}",
"assetKey": "assetKeyString"
}
Change Asset Order
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 Default: true , only the staged assets is updated. If false , both the current and staged assets are updated.true |
assetOrder Array of String | All existing Asset id s of the ProductVariant in the desired new order. |
{
"action": "changeAssetOrder",
"variantId": 1,
"assetOrder": [
"{{assetId1}}",
"{{assetId2}}"
]
}
Change Asset Name
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 Default: true , only the staged Asset is updated. If false , both the current and staged Asset is updated.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. |
{
"action": "changeAssetName",
"variantId": 1,
"assetId": "{{assetId}}",
"name": {
"de": "Mein Asset",
"en": "My asset"
}
}
Set Asset Description
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 Default: true , only the staged Asset is updated. If false , both the current and staged Asset is updated.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. |
{
"action": "setAssetDescription",
"variantId": 1,
"assetId": "{{assetId}}",
"description": {
"de": "Dies ist eine Asset-Beschreibung",
"en": "This is an asset description"
}
}
Set Asset Sources
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 Default: true , only the staged Asset is updated. If false both the current and staged Asset is updated.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 |
{
"action": "setAssetSources",
"variantId": 1,
"assetId": "{{assetId}}",
"sources": [
{
"uri": "https://www.commercetools.de/ct-logo.svg",
"key": "vector"
}
]
}
Set Asset Custom Type
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 Default: true , only the staged Asset is updated. If false , both the current and staged Asset is updated.true |
assetId String | The id of the Asset to update. |
assetKey String | The key of the Asset to update. |
type | 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. |
{
"action": "setAssetCustomType",
"variantId": 1,
"assetId": "{{assetId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}
Set Asset CustomField
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 Default: true , only the staged Asset is updated. If false , both the current and staged Asset is updated.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 . |
{
"action": "setAssetCustomField",
"variantId": 1,
"assetId": "{{assetId}}",
"name": "exampleStringField",
"value": "TextString"
}
Set SearchKeywords
action String | "setSearchKeywords" |
searchKeywords | Value to set. |
staged Boolean | If Default: true , only the staged searchKeywords is updated. If false , both the current and staged searchKeywords are updated.true |
{
"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 Default: true , only the staged metaTitle is updated. If false , both the current and staged metaTitle are updated.true |
{
"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 Default: true , only the staged metaDescription is updated. If false , both the current and staged metaDescription are updated.true |
{
"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 Default: true , only the staged metaKeywords is updated. If false , both the current and staged metaKeywords are updated.true |
{
"action": "setMetaKeywords",
"metaKeywords": {
"de": "mein MetaKeyword",
"en": "my metaKeeyword"
}
}
Revert Staged Changes
action String | "revertStagedChanges" |
{
"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. |
{
"action": "revertStagedVariantChanges",
"variantId": 2
}
Publish
action String | "publish" |
scope | All or Prices |
{
"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. ThehasStagedChanges
flag is updated according to whether the staged and current projections still differ after the prices are published.
Unpublish
staged
parameter must be set to false
when querying/searching Product Projections. Produces the ProductUnpublished Message.When a Product is unpublished, any associated Line Items already present in a Cart remain unaffected and can still be ordered. To prevent this, do the following:
- If the Product uses Embedded Prices, remove the Embedded Prices from the unpublished Product.
- If the Product uses Standalone Prices, inactivate or delete the Standalone Prices.
action String | "unpublish" |
{
"action": "unpublish"
}
Transition State
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" |
state | The State to transition to. If there is no existing State, this must be an initial State. |
force Boolean | If true , validations are disabled. |
{
"action": "transitionState",
"state": {
"typeId": "state",
"id": "{{state-id}}"
}
}
Upload Product image
InvalidInput
and the message Unsupported image data. Not able to identify the color model of your image.
In such case, you must fix the issue and upload the image again. If any other error response is returned, upload the image again.
url
might be shared across different Products in either the same Project or in other Projects.
However, if you delete any Product Variant that contains the image or if you remove the image from any Product Variant, then the image will be deleted from the CDN and it will no longer be available at its original URL.200 OK
, and if the image is larger, it responds with 202 Accepted
.- A
200 OK
response is returned when all sizes of the image have been successfully uploaded to the CDN. - A
202 Accepted
response is returned when thesmall
size of the image has been successfully uploaded to the CDN, but the upload of the other sizes is still ongoing. These other sizes will be available soon thereafter.
variant
or sku
is required to update a specific ProductVariant.
If neither is provided, the image is uploaded to the Master Variant of the Product.200 OK
, and if the image is larger, it responds with 202 Accepted
.
The Product returned with a 202 Accepted
status code contains a warnings
field with an ImageProcessingOngoing Warning.manage_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the Product. |
filename String | 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. Default: img |
variant Int | The id of the ProductVariant the image should be uploaded to. |
sku String | The sku of the ProductVariant the image should be uploaded to. |
staged Boolean | If true , only the staged ProductVariant is updated.
If false , both the current and staged ProductVariant are updated.Default: true |
Request headers:
Content-Type String | One of image/jpeg , image/png , or image/gif . |
image/jpeg
image/png
image/gif
.
Request headers:
Content-Type String | One of image/jpeg , image/png , or image/gif . |
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"
filename
parameter was included (filename=detail.jpg
), an example URL of the uploaded image is https://{commercetools-cdn}/detail-6xAq4Efp.jpg
.Delete Product
Delete Product by ID
manage_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the Product. |
version Int | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | Enables Product price selection and Scoped Price Search.
It can be used only in conjunction with the priceCurrency parameter.Pattern: ^[A-Z]{2}$ |
priceCustomerGroup String | id of an existing CustomerGroup used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
priceCustomerGroupAssignments String | IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups.
It can be used only in conjunction with the priceCurrency parameter.The parameter can be passed multiple times. |
priceChannel String | id of an existing Channel used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/products/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
manage_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the Product. |
version Int | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
priceCurrency | Enables Product price selection and Scoped Price Search. Pattern: ^[A-Z]{3}$ |
priceCountry | Enables Product price selection and Scoped Price Search.
It can be used only in conjunction with the priceCurrency parameter.Pattern: ^[A-Z]{2}$ |
priceCustomerGroup String | id of an existing CustomerGroup used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
priceCustomerGroupAssignments String | IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups.
It can be used only in conjunction with the priceCurrency parameter.The parameter can be passed multiple times. |
priceChannel String | id of an existing Channel used for Product price selection.
It can be used only in conjunction with the priceCurrency parameter. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/products/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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"
}