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

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` ProductTypeReference	The Product Type defining the Attributes of the Product. Cannot be changed.
`masterData` ProductCatalogData	Contains the current and the staged representation of the product information.
`taxCategory` TaxCategoryReference	The TaxCategory of the Product.
`state` StateReference	State of the Product.
`reviewRatingStatistics` ReviewRatingStatistics	Review statistics of the Product.
`priceMode` ProductPriceModeEnum	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 LastModifiedBy	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": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

ProductDraft

`key` String	User-defined unique identifier for the Product. This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing Products with the Import API and the Merchant Center. To update a Product using the Import API or Merchant Center, the Product `key` must match the pattern `^[A-Za-z0-9_-]{2,256}$`.
`productType` ProductTypeResourceIdentifier	The Product Type defining the Attributes for the Product. Cannot be changed later.
`name` LocalizedString	Name of the Product.
`slug` LocalizedString	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` LocalizedString	Description of the Product.
`categories` Array of CategoryResourceIdentifier	Categories assigned to the Product.
`categoryOrderHints` CategoryOrderHints	Numerical values to allow ordering of Products within a specified Category.
`metaTitle` LocalizedString	Title of the Product as used by search engines.
`metaDescription` LocalizedString	Description of the Product as used by search engines.
`metaKeywords` LocalizedString	Keywords that give additional information about the Product to search engines.
`masterVariant` ProductVariantDraft	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` TaxCategoryResourceIdentifier	The Tax Category to be assigned to the Product.
`searchKeywords` SearchKeywords	Used by Product Suggestions, but is also considered for a full text search.
`state` StateResourceIdentifier	State to be assigned to the Product.
`publish` Boolean	If `true`, the Product is published immediately to the current projection. Default: `false`
`priceMode` ProductPriceModeEnum	Specifies the type of prices used when looking up a price for the Product. Default: `Embedded`

Example: json

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

ProductPagedQueryResponse

PagedQueryResult with results containing an array of Product.

`limit` Int	Number of results requested. Default: `20`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10 000`
`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

Reference to a Product.

`id` String	Unique identifier of the referenced Product.
`typeId` ReferenceTypeId	`"product"` References a Product.
`obj` Product	Contains the representation of the expanded Product. Only present in responses to requests with Reference Expansion for Products.

ProductResourceIdentifier

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

`id` String	Unique identifier of the referenced Product. Required if `key` is absent.
`key` String	User-defined unique identifier of the referenced Product. Required if `id` is absent.
`typeId` ReferenceTypeId	`"product"` References a Product.

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` LocalizedString	Name of the Product.
`categories` Array of CategoryReference	Categories assigned to the Product.
`categoryOrderHints` CategoryOrderHints	Numerical values to allow ordering of Products within a specified Category.
`description` LocalizedString	Description of the Product.
`slug` LocalizedString	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` LocalizedString	Title of the Product as used by search engines.
`metaDescription` LocalizedString	Description of the Product as used by search engines.
`metaKeywords` LocalizedString	Keywords that give additional information about the Product to search engines.
`masterVariant` ProductVariant	The Master Variant of the Product.
`variants` Array of ProductVariant	Additional Product Variants. MaxItems: `100`
`searchKeywords` SearchKeywords	Used by Product Suggestions, but is also considered for a full text search.

CategoryOrderHints

JSON object where the key is a Category id and the value is an order hint. Allows controlling the order of Products and how they appear in Categories. Products with no order hint have an order score below 0. Order hints are non-unique. If a subset of Products have the same value for order hint in a specific category, the behavior is undetermined.

/[0-9].[0-9]*[1-9]/

Any string parameter matching this regular expression

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

Example: json

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

SearchKeywords

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

{
  "en": [
    { "text": "Multi tool" },
    { "text": "Swiss Army Knife", "suggestTokenizer": { "type": "whitespace" } }
  ],
  "de": [
    {
      "text": "Schweizer Messer",
      "suggestTokenizer": {
        "type": "custom",
        "inputs": ["schweizer messer", "offiziersmesser", "sackmesser"]
      }
    }
  ]
}

SearchKeyword

`text` String	Text to return in the SuggestionResult.
`suggestTokenizer` SuggestTokenizer	If no tokenizer is defined, the `text` is used as a single token.

SuggestTokenizer

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

Whitespace Tokenizer

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

type

String

"whitespace"

Custom Tokenizer

Define arbitrary tokens that are used to match the input.

`type` String	`"custom"`
`inputs` Array of String	Contains custom tokens.

ProductVariant

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

`id` Int	A unique, sequential identifier of the Product Variant within the Product.
`key` String	User-defined unique identifier of the ProductVariant. This is different from Product `key`.
`sku` String	User-defined unique SKU of the Product Variant.
`prices` Array of Price	The Embedded Prices of the Product Variant. Cannot contain two Prices of the same Price scope (with same currency, country, Customer Group, Channel, `validFrom` and `validUntil`). 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` ProductVariantAvailability	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.

ProductVariantDraft

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

`key` String	User-defined unique identifier for the ProductVariant.
`sku` String	User-defined unique SKU of the Product Variant.
`prices` Array of PriceDraft	The Embedded Prices for the Product Variant. Each Price must have its unique Price scope (with same currency, country, Customer Group, Channel, `validFrom` and `validUntil`). MaxItems: `100`
`attributes` Array of Attribute	Attributes according to the respective AttributeDefinition.
`images` Array of Image	Images for the Product Variant.
`assets` Array of AssetDraft	Media assets for the Product Variant.

Attribute

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

name

String

Name of the Attribute.

value

Any

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

For Enum Type and Localized Enum Type, use the key of the Plain Enum Value or Localized Enum Value objects, or the complete objects as value.
For Localizable Text Type, use the LocalizedString object as value.
For Money Type Attributes, use the Money object as value.
For Set Type Attributes, use the entire set object as value.
For Nested Type Attributes, use the list of values of all Attributes of the nested Product as value.
For Reference Type Attributes, use the Reference object as value.

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` ImageDimensions	Dimensions of the original image.
`label` String	Custom label for the image.

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

-thumb (50x50) - example
-small (150x150) - example
-medium (400x400) - example
-large (700x700) - example
-zoom (1400x1400) - example
the original size of the uploaded image is provided without a suffix - example

Images will never be scaled up. If the original image is tiny, it will keep its original size, even in the "large" and "zoom" sizes.

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

ImageDimensions

`w` Int	Width of the image.
`h` Int	Height of the image.

ProductVariantAvailability

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` ProductVariantChannelAvailabilityMap	For each InventoryEntry with a supply Channel, an entry is added to `channels`.
`isOnStock` Boolean	Indicates whether a Product Variant is in stock.
`restockableInDays` Int	Number of days to restock a Product Variant once it is out of stock.
`availableQuantity` Int	Number of items of the Product Variant that are in stock.

ProductVariantChannelAvailabilityMap

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

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

ProductVariantChannelAvailability

`id` String	Unique identifier of the InventoryEntry.
`version` Int	Current version of the InventoryEntry.
`isOnStock` Boolean	Indicates whether a Product Variant is in stock in a specified Channel.
`restockableInDays` Int	Number of days to restock a Product Variant once it is out of stock in a specified Channel.
`availableQuantity` Int	Number of items of this Product Variant that are in stock in a specified Channel.

ProductPriceMode

This mode determines the type of Prices used for 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` CustomerGroupReference	Reference to a CustomerGroup.
`channel` ChannelReference	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` DiscountedPrice	Is set when a matching ProductDiscount exists. If set, the Cart uses the discounted value for the Cart Price calculation. When a relative Product Discount is applied and the fractional part of the discounted Price is 0.5, the discounted Price is rounded half down in favor of the Customer.
`custom` 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` Expansion	The parameter can be passed multiple times.
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.

Response:

200Productasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/products/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Get Product by Key

GET

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

If 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` Expansion	The parameter can be passed multiple times.
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.

Response:

200Productasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/products/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Query Products

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

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

GET

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

If 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` QueryPredicate	Query Predicates on Product Attributes are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types. The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20`
`offset` Int	Number of elements skipped. Default: `0`
`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` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200ProductPagedQueryResponseasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/products -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ProductPagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
      "masterData": {
        "current": {
          "categories": [
            {
              "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
              "typeId": "category"
            }
          ],
          "description": {
            "en": "Sample description"
          },
          "masterVariant": {
            "attributes": [],
            "id": 1,
            "images": [
              {
                "dimensions": {
                  "h": 1400,
                  "w": 1400
                },
                "url": "https://commercetools.com/cli/data/253245821_1.jpg"
              }
            ],
            "prices": [
              {
                "value": {
                  "type": "centPrecision",
                  "fractionDigits": 2,
                  "centAmount": 10000,
                  "currencyCode": "EUR"
                },
                "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
              }
            ],
            "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
          },
          "name": {
            "en": "MB PREMIUM TECH T"
          },
          "slug": {
            "en": "mb-premium-tech-t1369226795424"
          },
          "variants": [],
          "searchKeywords": {}
        },
        "hasStagedChanges": false,
        "published": true,
        "staged": {
          "categories": [
            {
              "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
              "typeId": "category"
            }
          ],
          "description": {
            "en": "Sample description"
          },
          "masterVariant": {
            "attributes": [],
            "id": 1,
            "images": [
              {
                "dimensions": {
                  "h": 1400,
                  "w": 1400
                },
                "url": "https://commercetools.com/cli/data/253245821_1.jpg"
              }
            ],
            "prices": [
              {
                "value": {
                  "type": "centPrecision",
                  "fractionDigits": 2,
                  "centAmount": 10000,
                  "currencyCode": "EUR"
                },
                "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
              }
            ],
            "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
          },
          "name": {
            "en": "MB PREMIUM TECH T"
          },
          "slug": {
            "en": "mb-premium-tech-t1369226795424"
          },
          "variants": [],
          "searchKeywords": {}
        }
      },
      "productType": {
        "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
        "typeId": "product-type"
      },
      "taxCategory": {
        "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
        "typeId": "tax-category"
      },
      "version": 2,
      "createdAt": "1970-01-01T00:00:00.001Z",
      "lastModifiedAt": "1970-01-01T00:00:00.001Z"
    }
  ]
}

Query Product Selections for Product

Retrieves Product Selections that contain the given Product.

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` QueryPredicate	The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20`
`offset` Int	Number of elements skipped. Default: `0`
`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`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200AssignedProductSelectionPagedQueryResponseasapplication/json

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` QueryPredicate	The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20`
`offset` Int	Number of elements skipped. Default: `0`
`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`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200AssignedProductSelectionPagedQueryResponseasapplication/json

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 for a given id. Returns a 200 OK status if the Product exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the Product.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/products/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Product exists by Key

HEAD

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

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

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Product.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/products/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Product exists by Query Predicate

HEAD

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

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

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

where

QueryPredicate

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

The parameter can be passed multiple times.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/products -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Create Product

POST

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

To create a new Product, send a representation that is going to become the initial staged and current representation of the new Product in the catalog. If 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` Expansion	The parameter can be passed multiple times.
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.

Request Body:ProductDraftasapplication/json

Response:

201Productasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/products -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "productType" : {
    "id" : "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId" : "product-type"
  },
  "categories" : [ {
    "typeId" : "category",
    "id" : "24f510c3-f334-4099-94e2-d6224a8eb919"
  } ],
  "name" : {
    "en" : "Some Product"
  },
  "slug" : {
    "en" : "product_slug_<random-uuid>"
  },
  "masterVariant" : {
    "sku" : "SKU-1",
    "prices" : [ {
      "value" : {
        "currencyCode" : "EUR",
        "centAmount" : 4200
      }
    } ],
    "images" : [ {
      "url" : "http://my.custom.cdn.net/master.png",
      "label" : "Master Image",
      "dimensions" : {
        "w" : 303,
        "h" : 197
      }
    } ]
  },
  "variants" : [ {
    "images" : [ {
      "url" : "http://my.custom.cdn.net/variant.png",
      "label" : "Variant Image",
      "dimensions" : {
        "w" : 303,
        "h" : 197
      }
    } ]
  } ]
}
DATA

201 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Update Product

Update Product by ID

POST

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

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

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

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the Product.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used 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:

200Productasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/products/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 2,
  "actions" : [ {
    "action" : "setDescription",
    "description" : {
      "en" : "The best product ever!"
    }
  } ]
}
DATA

200 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Update Product by Key

POST

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

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

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Product.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used 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:

200Productasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/products/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 2,
  "actions" : [ {
    "action" : "setDescription",
    "description" : {
      "en" : "The best product ever!"
    }
  } ]
}
DATA

200 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Set Product Key

`action` String	`"setKey"`
`key` String	Value to set. If empty, any existing value will be removed. To update a Product using the Import API and the Merchant Center, the Product `key` must match the pattern `^[A-Za-z0-9_-]{2,256}$`.

Example: json

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

Change Product Name

`action` String	`"changeName"`
`name` LocalizedString	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` LocalizedString	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` LocalizedString	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` ProductPriceModeEnum	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` TypeResourceIdentifier	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` FieldContainer	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` CustomFieldValue	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` DiscountedPriceDraft	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	The name of the Attribute to set.
`value` Any	Value to set for the Attribute. If empty, any existing value will be removed. The AttributeType determines the format of the Attribute `value` to be provided: For Enum Type and Localized Enum Type, use the `key` of the Plain Enum Value or Localized Enum Value objects, or the complete objects as `value`. For Localizable Text Type, use the LocalizedString object as `value`. For Money Type Attributes, use the Money object as `value`. For Set Type Attributes, use the entire `set` object as `value`. For Nested Type Attributes, use the list of values of all Attributes of the nested Product as `value`. For Reference Type Attributes, use the Reference object as `value`.
`staged` Boolean	If `true`, only the staged Attribute is set. If `false`, both current and staged Attribute is set. Default: `true`

Example: json

{
  "action": "setAttribute",
  "variantId": 1,
  "name": "ExampleStringTypeAttribute",
  "value": "TextString"
}

Set Attribute In All Variants

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

`action` String	`"setAttributeInAllVariants"`
`name` String	The name of the Attribute to set.
`value` Any	Value to set for the Attributes. If empty, any existing value will be removed. The AttributeType determines the format of the Attribute `value` to be provided: For Enum Type and Localized Enum Type, use the `key` of the Plain Enum Value or Localized Enum Value objects, or the complete objects as `value`. For Localizable Text Type, use the LocalizedString object as `value`. For Money Type Attributes, use the Money object as `value`. For Set Type Attributes, use the entire `set` object as `value`. For Nested Type Attributes, use the list of values of all Attributes of the nested Product as `value`. For Reference Type Attributes, use the Reference object as `value`.
`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` CategoryResourceIdentifier	The Category to add.
`orderHint` String	A string representing a number between 0 and 1. Must start with `0.` and cannot end with `0`. If empty, any existing value will be removed. Pattern: `^0.[0-9]*[1-9]$`
`staged` Boolean	If `true`, only the staged `categories` and `categoryOrderHints` are updated. If `false`, both the current and staged `categories` and `categoryOrderHints` are updated. Default: `true`

Example: json

{
  "action": "addToCategory",
  "category": {
    "typeId": "category",
    "id": "{{category-id}}"
  }
}

Set Category Order Hint

`action` String	`"setCategoryOrderHint"`
`categoryId` String	The `id` of the Category to add the `orderHint`.
`orderHint` String	A string representing a number between 0 and 1. Must start with `0.` and cannot end with `0`. If empty, any existing value will be removed. Pattern: `^0.[0-9]*[1-9]$`
`staged` Boolean	If `true`, only the staged `categoryOrderHints` is updated. If `false`, both the current and staged `categoryOrderHints` are updated. Default: `true`

Example: json

{
  "action": "setCategoryOrderHint",
  "categoryId": "{{category-id}}",
  "orderHint": "0.1"
}

Remove from Category

Produces the ProductRemovedFromCategory Message.

`action` String	`"removeFromCategory"`
`category` CategoryResourceIdentifier	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` TaxCategoryResourceIdentifier	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 `id`s 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` LocalizedString	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` LocalizedString	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` TypeResourceIdentifier	Defines the Type that extends the Asset with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Asset.
`fields` FieldContainer	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` CustomFieldValue	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` 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` LocalizedString	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` LocalizedString	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` LocalizedString	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` ProductPublishScope	`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:

If the Product uses Embedded Prices, remove the Embedded Prices from the unpublished Product.
If the Product uses Standalone Prices, inactivate or delete the Standalone Prices.

action

String

"unpublish"

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` StateResourceIdentifier	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:

200Productasapplication/json202Productasapplication/json

200 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

202 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z",
  "warnings": [
    {
      "code": "ImageProcessingOngoing",
      "message": "The image processing is still ongoing."
    }
  ]
}

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

  curl -X POST  \
   -H "Content-Type: image/jpeg"  \
   -H "Authorization: Bearer {token}" \
   --upload-file "detail.jpg" \
   "https://api.{region}.commercetools.com/{projectKey}/products/{id}/images?variant=2&filename=detail.jpg"

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

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

Delete Product

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

Delete Product by ID

DELETE

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

If 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` Expansion	The parameter can be passed multiple times.
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.

Response:

200Productasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/products/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Delete Product by Key

DELETE

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

If 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` Expansion	The parameter can be passed multiple times.
`priceCurrency` CurrencyCode	The currency used for Product price selection.
`priceCountry` CountryCode	The country used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceCustomerGroup` String	`id` of an existing CustomerGroup used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.
`priceChannel` String	`id` of an existing Channel used for Product price selection. Can only be used in conjunction with the `priceCurrency` parameter.

Response:

200Productasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/products/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Productjson

{
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "version": 2,
  "masterData": {
    "current": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    },
    "hasStagedChanges": false,
    "published": true,
    "staged": {
      "categories": [
        {
          "id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb",
          "typeId": "category"
        }
      ],
      "description": {
        "en": "Sample description"
      },
      "masterVariant": {
        "attributes": [],
        "id": 1,
        "images": [
          {
            "dimensions": {
              "h": 1400,
              "w": 1400
            },
            "url": "https://commercetools.com/cli/data/253245821_1.jpg"
          }
        ],
        "prices": [
          {
            "value": {
              "type": "centPrecision",
              "fractionDigits": 2,
              "centAmount": 10000,
              "currencyCode": "EUR"
            },
            "id": "753472a3-ddff-4e0f-a93b-2eb29c90ba54"
          }
        ],
        "sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424"
      },
      "name": {
        "en": "MB PREMIUM TECH T"
      },
      "slug": {
        "en": "mb-premium-tech-t1369226795424"
      },
      "variants": [],
      "searchKeywords": {}
    }
  },
  "productType": {
    "id": "24f510c3-f334-4099-94e2-d6224a8eb919",
    "typeId": "product-type"
  },
  "taxCategory": {
    "id": "f1e10e3a-45eb-49d8-ad0b-fdf984202f59",
    "typeId": "tax-category"
  },
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Products

Representations

Product

ProductDraft

ProductPagedQueryResponse

ProductReference

ProductResourceIdentifier

ProductCatalogData

ProductData

CategoryOrderHints

SearchKeywords

SearchKeyword

SuggestTokenizer

Whitespace Tokenizer

Custom Tokenizer

ProductVariant

ProductVariantDraft

Attribute

Image

ImageDimensions

ProductVariantAvailability

ProductVariantChannelAvailabilityMap

ProductVariantChannelAvailability

ProductPriceMode

ScopedPrice

Get Product

Get Product by ID

Get Product by Key

Query Products

Query Product Selections for Product

by Product ID

by Product Key

Check if Product exists

Check if Product exists by ID

Check if Product exists by Key

Check if Product exists by Query Predicate

Create Product

Update Product

Update Product by ID

Update Product by Key

Update actions

Set Product Key

Change Product Name

Set Product Description

Change Slug

Add ProductVariant

Remove ProductVariant

Change Master Variant

Set PriceMode

Add Price

Set Prices

Change Price

Remove Price

Set Price Custom Type

Set Price CustomField

Set Discounted Price

Set Price Key

Set Attribute

Set Attribute In All Variants

Add to Category

Set Category Order Hint

Remove from Category

Set TaxCategory

Set SKU

Set ProductVariant Key

Add External Image

Move Image To Position

Remove Image

Set Image Label

Add Asset

Remove Asset

Set Asset Key

Change Asset Order

Change Asset Name

Set Asset Description

Set Asset Tags

Set Asset Sources

Set Asset Custom Type

Set Asset CustomField

Set SearchKeywords