Products

Products represent the sellable goods in a 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.
Learn more about Products in our self-paced Product data modeling and Advanced Product data modeling modules.

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​
DateTime​

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

createdBy​BETA
CreatedBy​

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.
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": {},
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    },
    "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": {},
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    }
  },
  "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

If the key value of ProductDraft is modified, any Product Tailoring associated with the Product will be removed.
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​

Categories assigned to the Product.

categoryOrderHints​
Numerical values to allow ordering of Products within specified Categories. If the referenced Categories are not also assigned in the categories field, an InvalidOperation error is returned.
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 Search Term Suggestions, but is also considered for a full text search in the Product Projection Search API.
state​

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​
attributes​BETA
Array of Attribute​
Attributes according to the respective AttributeDefinition.
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
          }
        }
      ]
    }
  ],
  "attributes": [
    {
      "name": "label",
      "value": "product-attribute"
    }
  ]
}

ProductPagedQueryResponse

PagedQueryResult with results containing an array of Product.
limit​
Int​
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​
Product​
Contains the representation of the expanded Product. Only present in responses to requests with Reference Expansion for Products.

ProductKeyReference

Used by the Import API to identify a Product.
key​
String​

User-defined unique identifier of the referenced Product.

typeId​
product

Type of referenced resource.

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​
product
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

ProductCatalogData

Contains the current and staged ProductData.
published​
Boolean​
true if the Product is published.
current​
ProductData​

Current (published) data of the Product.

staged​
ProductData​

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 Search Term Suggestions, but is also considered for a full text search in the Product Projection Search API.
attributes​BETA
Array of Attribute​
Attributes according to the respective AttributeDefinition.

CategoryOrderHints

JSON object where the keys are Category id, and the values are order hint values: strings representing a number between 0 and 1, but not ending in 0. Order hints allow controlling the order of Products and how they appear in Categories. Products without order hints have an order score below 0. Order hints are not unique.

If a subset of Products have the same value for order hint in a specific category, the behavior is undetermined.

Example:json
{
  "1d20faef-e8e1-44f4-b1b9-3a25b68fd266": "0.1234",
  "ed9556d2-203f-4c80-840d-79305f341ba8": "0.5678"
}

SearchKeywords

Search keywords are primarily used by Search Term Suggestions, but are also considered for a full-text search in the Product Projection Search API.
Search keywords are JSON objects primarily used by Search Term Suggestions, but are also considered for a full text search in the Product Projection Search API. The keys are of type Locale, and the values are an array of SearchKeyword.
/^[a-z]{2}(-[A-Z]{2})?$/​
Array of SearchKeyword​
Key-value pair where the keys are of type Locale and the values are an array of SearchKeyword.
Example: json
{
  "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

Defines tokens that are used for Search Term Suggestions. 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).
MaxItems: 100​
attributes​
Array of Attribute​

Attributes of the Product Variant.

price​
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​
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.
recurrencePrices​BETA
Array of Price​
Only available when Product price selection is used. Cannot be used in a Query Predicate.

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.

ProductVariantKeyReference

Used by the Import API to identify a ProductVariant.
key​
String​

User-defined unique identifier of the referenced ProductVariant.

typeId​
product-variant

Type of referenced resource.

Attribute

You can configure Attributes either at the variant level or at the Product level. For more information about the difference between the two, see AttributeDefinition.
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.
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.

Learn more about images in our self-paced Images and Assets module.

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

JSON object where the keys are supply Channel id, and the values are ProductVariantChannelAvailability.
Example:json
{
  "cd724bd4-52fa-4d6d-b4b0-bb1560d70475": {
    "id": "f64af276-a1ad-4eea-a8bc-89c453742a40",
    "version": 3,
    "isOnStock": true,
    "restockableInDays": 10,
    "availableQuantity": 20
  },
  "f73fa437-e244-4d6f-8723-52b447427e0b": {
    "id": "beaa0b68-562b-4866-a42b-e61baf1043d1",
    "version": 5,
    "isOnStock": true,
    "restockableInDays": 5,
    "availableQuantity": 12
  }
}

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 price selection by Line Items and Products. For more information about the difference between the Prices, see Pricing.
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.
Regardless of the chosen Price mode, ProductVariant prices contains Embedded Prices only.

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​
TypedMoney​

Original value of the Price.

currentValue​
TypedMoney​
If available, either the original price value or discounted value.
country​
CountryCode​

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.
custom​
CustomFields​

Custom Fields for the Price.

Get Product

Get Product by ID

GET
https://api.{region}.commercetools.com/{projectKey}/products/{id}
If Product 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
​​
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.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
Response:
200

Product

asapplication/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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    },
    "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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    }
  },
  "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 Product 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
​​
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.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
Response:
200

Product

asapplication/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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    },
    "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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    }
  },
  "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 Attributes should not be used in high-volume use cases as it is an inefficient pattern.
We recommend using the performance-optimized Product Search API, which provides some functionalities that the query API lacks (including sorting by Attributes).
When querying an Attribute, you must always include both the attribute-name and attribute-value details in the Query Predicate. Otherwise, a 400 Bad Request error will occur.
GET
https://api.{region}.commercetools.com/{projectKey}/products
If Product price selection query parameters are provided, the selected Prices are added to the response.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_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 Attributes are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.
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
​
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
​​
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.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
var.<varName>
​
String
​
The parameter can be passed multiple times.
Response:
200

ProductPagedQueryResponse

asapplication/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": {

          },
          "attributes": [
            {
              "name": "label",
              "value": "product-attribute"
            }
          ]
        },
        "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": {

          },
          "attributes": [
            {
              "name": "label",
              "value": "product-attribute"
            }
          ]
        }
      },
      "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

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.
sort
​​
The parameter can be passed multiple times.
expand
​​
The parameter can be passed multiple times.
limit
​
Int
​
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 true to get the total number of query results. This may impact query performance.
Default: false​
var.<varName>
​
String
​
The parameter can be passed multiple times.
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"
    }
  ]
}

by Product Key

GET
https://api.{region}.commercetools.com/{projectKey}/products/key={key}/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.
key
​
String
​
key of the Product.
Query parameters:
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
​
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 true to get the total number of query results. This may impact query performance.
Default: false​
var.<varName>
​
String
​
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/products/key={key}/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 with the provided id. Returns a 200 status if the Product exists, or a 404 status 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 with the provided key. Returns a 200 status if the Product exists, or a 404 status 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 one or more Products exist for the provided query predicate. Returns a 200 status if any Products match the query predicate, or a 404 status 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 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 Product 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
​​
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.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
Request Body:ProductDraftasapplication/json
Response:
201

Product

asapplication/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
      }
    } ]
  } ],
  "attributes" : [ {
    "name" : "label",
    "value" : "product-attribute"
  } ]
}
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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    },
    "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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    }
  },
  "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 Product price selection query parameters are provided, the selected Prices are added to the response.
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
​​
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.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
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​
Array of ProductUpdateAction​

Update actions to be performed on the Product.

Response:
200

Product

asapplication/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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    },
    "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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    }
  },
  "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
​​
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.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
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​
Array of ProductUpdateAction​

Update actions to be performed on the Product.

Response:
200

Product

asapplication/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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    },
    "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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    }
  },
  "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

Modifying the key will remove any Product Tailoring associated with the Product.

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}$.
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

If the Product Variant contains 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.
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

This action does not affect the behavior of the Add Price, Set Prices, Change Price, and Remove Price update actions as they are only meant for managing Embedded Prices.
When changing the Price mode, no migration of Prices takes place between Embedded Prices and StandalonePrices.

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​
PriceDraft​

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).
MaxItems: 100​
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​
PriceDraft​

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​
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.
Example: json
{
  "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 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": "exampleStringField",
  "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: 2​MaxLength: 256​Pattern: ^[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​

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 the current and staged Attributes are set.
Default: true​
Example: json
{
  "action": "setAttribute",
  "variantId": 1,
  "name": "ExampleStringTypeAttribute",
  "value": "TextString"
}

Set Product Attribute

action​
String​
"setProductAttribute"
name​
String​

Name of the Product 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 the current and staged Attributes are set.
Default: true​
Example: json
{
  "action": "setProductAttribute",
  "name": "ExampleStringTypeAttribute",
  "value": "TextString"
}

Set Attribute In All Variants

Adds, removes, or changes a Variant 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​

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"
category​

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. If this Category is not assigned to the Product, an InvalidOperation error is returned.
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"
category​

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"
taxCategory​

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​
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

If the image that you want to delete has been uploaded to our CDN and its url is also used on other Product Variants, then removing the image will make it unavailable wherever it is shared.
Removes a Product image and deletes it from the Content Delivery Network (CDN) if it had been uploaded to our CDN. External images will not be deleted. The API deletes the removed image from the CDN in an eventual consistent way. 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​
AssetDraft​

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: 2​MaxLength: 256​Pattern: ^[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.
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.
Example: json
{
  "action": "setAssetCustomType",
  "variantId": 1,
  "assetId": "{{assetId}}",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "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": "exampleStringField",
  "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"
scope​
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.

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:

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"
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.
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 uploading 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. In such case, you must fix the issue and upload the image again.
If any other error response is returned, upload the image again.
The image uploaded to the CDN is publicly available and its 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.
Depending on the size of the original image, the API returns different status codes that indicate the status of the image upload at the time the API responds. If the original image is small, the API responds with 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 the small 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.
POST
https://api.{region}.commercetools.com/{projectKey}/products/{id}/images
Uploads a JPEG, PNG, or a GIF image file to a ProductVariant. The maximum file size of the image is 10MB. Either 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.
The response status code depends on the size of the original image. If the image is small, the API responds with 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.
Produces the ProductImageAdded 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:
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.
Request Body:
image/jpeg
orimage/png
orimage/gif

.

The file to upload
Response:
200

Product

asapplication/json
202

Product

asapplication/json

Request headers:

Content-Type
​
String
​
One of image/jpeg, image/png, or image/gif.
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.
Learn more about images in our self-paced Images and Assets module.

Delete Product

You can only delete unpublished Products. This will also remove all Product Tailoring associated with the Product.

Delete Product by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/products/{id}
If Product 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
​​
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.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
Response:
200

Product

asapplication/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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    },
    "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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    }
  },
  "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 Product 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
​​
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.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
Response:
200

Product

asapplication/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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    },
    "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": {

      },
      "attributes": [
        {
          "name": "label",
          "value": "product-attribute"
        }
      ]
    }
  },
  "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"
}