Products

Products are the sellable goods in an e-commerce project on the commercetools platform.

Products contain ProductVariants, which represent a single sellable product (often an individual SKU). Mapping your goods to commercetools products and variants efficiently is an important part of working with the platform. For more information, see the Product Modeling Guide.

Product

The full representation of a product combines the current and staged representations in a single representation.

id - String
The unique ID of the product.
key - String - Optional
User-specific unique identifier for the product. Product keys are different from product variant keys.
version - Number
The current version of the product.
createdAt - DateTime
createdBy - CreatedBy BETA
Present on resources created after 2019-02-01 except for events not tracked.
lastModifiedAt - DateTime
lastModifiedBy - LastModifiedBy BETA
Present on resources updated after 2019-02-01 except for events not tracked.
productType - Reference to a ProductType
masterData - ProductCatalogData
The product data in the master catalog.
taxCategory - Reference to a TaxCategory - Optional
state - Reference to a State - Optional
reviewRatingStatistics - ReviewRatingStatistics - Optional
Statistics about the review ratings taken into account for this product.

ProductCatalogData

published - Boolean
Whether the product is published.
current - ProductData
The current data of the product.
staged - ProductData
The staged data of the product.
hasStagedChanges - Boolean
Whether the staged data is different from the current data.

ProductData

name - LocalizedString
categories - Array of Reference to a Category
References to categories the product is in.
categoryOrderHints - CategoryOrderHints - Optional
description - LocalizedString - Optional
slug - LocalizedString
Human-readable identifiers usually used as deep-link URL to the related product. Each slug is unique across a project, but a product can have the same slug for different languages.
For good performance, indexes are provided for the first 15 languages set on the Project.
metaTitle - LocalizedString - Optional
metaDescription - LocalizedString - Optional
metaKeywords - LocalizedString - Optional
masterVariant - ProductVariant
variants - Array of ProductVariant
searchKeywords - SearchKeywords

ProductVariant

id - Number
The sequential ID of the variant within the product.
sku - String - Optional
The unique SKU of the variant.
key - String - Optional
User-specific unique identifier for the variant. Product variant keys are different from product keys.
prices - Array of Price - Optional
The prices of the variant. The prices does not contain two prices for the same price scope (same currency, country, customer group and channel).
attributes - Array of Attribute - Optional
price - Price - Optional
Only appears when price selection is used. This field cannot be used in a query predicate.
images - Array of Image - Optional
assets - Array of Asset - Optional
availability - ProductVariantAvailability - Optional
The availability is set if the variant is tracked by the inventory. The field might not contain the latest inventory state (it is eventually consistent) and can be used as an optimization to reduce calls to the inventory service.
isMatchingVariant - Boolean - Optional
Only appears in response to a Product Projection Search request to mark this variant as one that matches the search query.
scopedPrice - ScopedPrice - Optional
Only appears when price selection is used.
scopedPriceDiscounted - Boolean - Optional
Only appears in response to a Product Projection Search request when price selection is used.

ProductVariantAvailability

isOnStock - Boolean - Optional
restockableInDays - Number - Optional
The number of days it takes to restock a product once it is out of stock.
availableQuantity - Number - Optional
The number of items of this product variant that are currently available in stock
isOnStock, restockableInDays and quantityOnStock are based on the Inventory Entry with no supply channel for this variant.
channels - Map of ProductVariantAvailability per Channel id - Optional
For each Inventory Entries with a supply channel, an entry is added into channels:
- the key is the Channel id
- the value is an object containing the data isOnStock, restockableInDays and availableQuantity for the Inventory Entry with the supply channel for this variant.

Price

id - String - read only
The unique ID of this price.
value - BaseMoney
country - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2.
customerGroup - Reference to a CustomerGroup - Optional
A reference to a customer group.
channel - Reference to a Channel - Optional
A reference to a channel.
validFrom - DateTime - Optional
Date from which the price is valid.
validUntil - DateTime - Optional
Date until which the price is valid.
tiers - Array of PriceTier - Optional
discounted - DiscountedPrice - Optional
Set if a matching ProductDiscount exists. If set, the Cart will use the discounted value for the cart price calculation.
When a relative discount is applied and the fraction part of the discounted price is 0.5, the discounted price is rounded in favor of the customer with the half down rounding.
custom - CustomFields - Optional

PriceTier

A price tier is selected instead of the default price when a certain quantity of the ProductVariant is added to a cart and ordered.
For example: the price can be lower if more than 10 items are ordered.
If no price tier is found for the order quantity, the base Price is used.
A price tier is applied for the entire quantity of a product variant put as LineItem in a cart as soon as the minimum quantity for the price tier is reached.
The price tier is applied per line item of the product variant. If, for example, the same product variant appears in the same cart as several line items, (what can be achieved by different values of a custom field on the line items) for each line item the minimum quantity must be reached to get the price tier.

minimumQuantity - Number
The minimum quantity this price tier is valid for.
The minimum quantity is always greater than or equal to 2 (the base Price is interpreted as valid for minimum quantity equals to 1).
value - BaseMoney
The currency of a price tier is always the same as the currency of the base Price.

DiscountedPrice

value - Money
discount - Reference to a ProductDiscount

ScopedPrice

Scoped price is returned as a part of a variant in product search (when price selector is used).

id - String - read only
The unique ID of this price.
value - BaseMoney - the original price value
currentValue - BaseMoney - either the original price value or the discounted value, if it's available
country - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2.
customerGroup - Reference to a CustomerGroup - Optional
A reference to a customer group.
channel - Reference to a Channel - Optional
A reference to a channel.
validFrom - DateTime - Optional
Date from which the price is valid.
validUntil - DateTime - Optional
Date until which the price is valid.
discounted - DiscountedPrice - Optional
Is set if a matching ProductDiscount exists. If set, the Cart will use the discounted value for the cart price calculation.
When a relative discount is applied and the fraction part of the discounted price is 0.5, the discounted price is rounded in favor of the customer with the half down rounding.
custom - CustomFields - Optional

ProductDraft

The representation sent to the server when creating a new product.

key - String - Optional
User-specific unique identifier for the product.
name - LocalizedString - Required
productType - ResourceIdentifier to a ProductType - Required
A predefined product type assigned to the product. All products must have a product type.
slug - LocalizedString - Required
Human-readable identifiers usually used as deep-link URLs for the product. A slug must be unique across a project, but a product can have the same slug for different languages. Slugs have a maximum size of 256.
Valid characters are: alphabetic characters (A-Z, a-z), numeric characters (0-9), underscores (_) and hyphens (-).
description - LocalizedString - Optional
categories - Array of ResourceIdentifier for a Category - Optional
Categories assigned to the product.
categoryOrderHints - CategoryOrderHints - Optional
metaTitle - LocalizedString - Optional
metaDescription - LocalizedString - Optional
metaKeywords - LocalizedString - Optional
masterVariant - ProductVariantDraft - Optional
The master product variant. Required if the variants array has product variants.
variants - Array of ProductVariantDraft - Optional
An array of related product variants.
taxCategory - ResourceIdentifier to a TaxCategory - Optional
searchKeywords - SearchKeywords - Optional
state - ResourceIdentifier to a State - Optional
publish - Boolean - Optional, defaults to false
If true, the product is published immediately.

ProductVariantDraft

sku - String - Optional
SKU must be unique.
key - String - Optional
User-specific unique identifier for the variant.
prices - Array of PriceDraft - Optional
The prices for the variant draft. A maximum number of 100 prices can be specified
images - Array of Image - Optional
External images for the variant draft. You can also upload images to use the commercetools platform's Content Delivery Network.
assets - Array of AssetDraft - Optional
attributes - Array of Attribute - Optional
The AttributeType determines the format for the attribute value to be provided, in particular:
- for EnumType and LocalizableEnumType attributes:
  - either only the key of the EnumValue or of the LocalizedEnumValue is to be used as value
  - or the complete EnumValue or the complete LocalizedEnumValue is to be used as value
- for LocalizableTextType attributes the LocalizedString object is to be used as value
- for MoneyType attributes the Money object is to be used as value
- for SetType attributes the entire set object is to be used as value
- for NestedType attributes the list of values of all attributes of the nested product is to be used as value
- for ReferenceType attributes the Reference object is to be used as value

PriceDraft

value - BaseMoney - Required
country - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. If not set, the price is valid for any country.
customerGroup - Reference to a CustomerGroup - Optional
A reference to a customer group.
channel - ResourceIdentifier to a Channel - Optional
Connection to a particular channel.
discounted - DiscountedPrice - Optional
Sets a discounted price from an external service. Absolute or relative ProductDiscounts prices are automatically added to a product's Price when created.
The DiscountedPrice must reference a ProductDiscount with:
- The isActive flag set to true.
- An external ProductDiscountValue.
- A predicate which matches the ProductVariant the Price is referenced from.
validFrom - DateTime - Optional
Date from which the price is valid.
validUntil - DateTime - Optional
Date until which the price is valid.
tiers - Array of PriceTier - Optional
custom - CustomFieldsDraft - Optional
The custom fields.

Price Selection

The cart addLineItem update action selects a price from the product's prices array based on the currency, country, customer group,channel, and a date. The product-related endpoints also provide the same price selection logic to help the shop to show the right price to the customer.

If the price selection parameter priceCurrency and any of the price selection parameters priceCountry, priceCustomerGroup and priceChannel are given as a query parameter and a matching price exists, a price field containing the matching price is added to the ProductVariant of the returned product projections.

Price validity dates are taken into account (see validFrom and validUntil in ProductVariant Price). The price is shown only when the timestamp of the request is within validFrom - ValidUntil range.

Changing the Date for Price Selection BETA

The priceDate parameter overrides the request's timestamp, selecting a valid price from the past or the future.

When priceDate does not equal the current date, product discounts are not taken into account. For example, if you create a product discount with validity dates in the future, and use priceDate in the product discount's timeframe, the future price selected will not include the product discount, even if the discount is valid for the date specified in the priceDate parameter.

Attribute

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

name - String
value - *
A valid JSON value, based on an AttributeDefinition.

Category Order Hints

Products can have a category order hint for each category they are assigned to. This allows controlling the order of products and how they appear in categories.

The category order hints is a JSON object where the keys are the category IDs, and the values are the corresponding order hint set for that category.

Order hints are strings representing valid number values between 0 and 1 while everything closer to 1 is interpreted as higher than everything closer to 0. Order hints thus always start with 0. and must never end with a 0 (always write 0.1 but never 0.10). Products that have no order hint have an order score below 0.

Order hints are non-unique. If a subset of products have the same value for order hint in a specific category, the behavior is undetermined.

Images

A product image can be uploaded using the image upload endpoint, or via the Merchant Center . An Image uploaded to the commercetools platform is stored in a Content Delivery Network and it's available in several pre-defined sizes.

If you already have an image stored on an external service, you can save the URL when creating a new product or adding a variant, or you can add it later. An image is represented in the following way:

url - String
URL of the image in its original size. The URL must be unique within a single variant. It can be used to obtain the image in different sizes - see below.
dimensions - {"w": Number, "h": Number}
Dimensions of the original image. This can be used by your application for example to determine whether the image is large enough to display a zoom view.
label - String - Optional
Custom label that can be used, for example, as an image description.

Images in specific sizes are obtained by appending a size suffix to the original URL (before the .jpg, .png etc. extension part of the filename):

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

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

Also note that images are not shared between variants - each variant has its own set of images. However, if you wish to have many variants with the same set of images, you can implement this in your application by always showing the images of the master variant, regardless of the selected variant.

SearchKeywords

Search keywords are primarily used by the suggester, but are also considered for the full text search. SearchKeywords is a JSON object where the keys are of IETF language tag. The value to a language tag key is an array of SearchKeyword for the specific language.

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

SearchKeyword

text - String
Text to return in the result of a suggest query.
suggestTokenizer - SuggestTokenizer - Optional
If no tokenizer is defined, the text is used as single token.

SuggestTokenizer

The tokenizer defines the tokens that are used to match against the suggest query input.

Whitespace Tokenizer

Whitespace tokenizer creates tokens by splitting the SearchKeyword text field by whitespaces.

type - whitespace

Custom Tokenizer

Custom tokenizer allows to define arbitrary tokens which are used to match the input.

type - custom
inputs - Array of String
Contains custom tokens

Get Product

Get Product by ID

Gets the full representation of a product by ID.

Endpoint: /{projectKey}/products/{id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: Product
Query Parameters:

priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.

Example RequestTerminal

#!/bin/sh
$curl "https://api.{region}.{cloudProvider}.commercetools.com/{projectKey}/products/e7ba4c75-b1bb-483d-94d8-2c4a10f78472" \
  -H "Authorization: Bearer YrT7pRnLXVIco7KHlere_X-HL0sWdWOE"

Example Responsejson

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

Get Product by Key

Gets the full representation of a product by Key.

Endpoint: /{projectKey}/products/key={key}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: Product
Query Parameters:

priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.

Query Products

You can use the query endpoint to get the full representations of products. We suggest to use the performance optimized search endpoint which has a bunch functionalities, the query API lacks like sorting on custom attributes, etc.

Endpoint: /{projectKey}/products
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results array of Product
Query Parameters:

where - Query Predicate - Optional
The predicate on product attributes is limited to text, enum, boolean, number, date, time and datetime attribute types.
sort - Sort - Optional
Sorting is only possible for data not nested in arrays. Examples are: SKU of masterVariant, createdAt, lastModifiedAt, name.en, etc. Sorting for prices or custom attributes via Query API is not possible.
expand - Expansion - Optional
limit - Number - Optional
offset - Number - Optional
priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.

Example RequestTerminal

#!/bin/sh
$curl "https://api.{region}.{cloudProvider}.commercetools.com/{projectKey}/products?where=masterData%28current%28name%28en%3D%22MB%20PREMIUM%20TECH%20T%22%29%29%29%20and%20id%20%3D%20%22e7ba4c75-b1bb-483d-94d8-2c4a10f78472%22" \
  -H "Authorization: Bearer YrT7pRnLXVIco7KHlere_X-HL0sWdWOE"
# decoded query:
# masterData(current(name(en="MB PREMIUM TECH T"))) and id = "e7ba4c75-b1bb-483d-94d8-2c4a10f78472"

Example Responsejson

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

Create a Product

To create a new product, send a representation that is going to become the initial staged representation of the new product in the master catalog. If price selection query parameters are provided, the selected prices will be added to the response.

Endpoint: /{projectKey}/products
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Request Representation: ProductDraft
Response Representation: Product
Query Parameters:

priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.

Creating a product produces the ProductCreated message.

Update Product

(Partial) updates are made to an existing product by sending a list of actions to be applied.
The actions are applied in the given order. If price selection query parameters are provided, the selected prices will be added to the response.

Update Product by ID

Endpoint: /{projectKey}/products/{id}
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:

priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.

Fields:

version - Number
The expected version of the product on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
actions - Array of UpdateAction - Required
The list of update actions to apply to the product.

Specific Error Codes:

Update Product by Key

Update a product found by its Key.

Endpoint: /{projectKey}/products/key={key}
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:

priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.

Fields:

version - Number
The expected version of the product on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
actions - Array of UpdateAction - Required
The list of update actions to apply to the product.

Specific Error Codes:

Set Key

action - String - "setKey"
key - String - Optional
User-specific unique identifier for the product.
If left blank or set to null, the product key is unset/removed.

Change Name

action - String - "changeName"
name - LocalizedString - Required
staged - Boolean - Optional (Default: true)

Set Description

action - String - "setDescription"
description - LocalizedString - Required
staged - Boolean - Optional (Defaults to true)

Change Slug

action - String - "changeSlug"
slug - LocalizedString - Required
Every slug must be unique across a project, but a product can have the same slug for different languages. Allowed are alphabetic, numeric, underscore (_) and hyphen (-) characters. Maximum size is 256.
staged - Boolean - Optional (Defaults to true)

Changing the slug produces the ProductSlugChanged message.

Add ProductVariant

action - String - "addVariant"
sku - String - Optional
SKU must be unique.
key - String - Optional
User-specific unique identifier for the variant.
prices - Array of Price - Optional. A maximum number of 100 prices can be specified on a ProductVariant.
images - Array of Image - Optional
External images for the new variant. You can also upload images to use the commercetools platform's Content Delivery Network.
attributes - Array of Object - Optional
The custom attributes of the master variant. Each attribute is a JSON object where a field name corresponds to the name of a product attribute defined on the referenced ProductType and the value being a valid JSON value for that attribute.
staged - Boolean - Optional (Defaults to true)
assets - Array of Asset - Optional

Remove ProductVariant

action - String - "removeVariant"
id - Number or sku - String - Required
staged - Boolean - Optional (Defaults to true)

Removing a product variant produces the ProductVariantDeleted message.

Change Master Variant

Sets the given variant as the new master variant. The previous master variant is added to the back of the list of variants.

action - String - "changeMasterVariant"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Defaults to true)

Add Price

Adds the given price to the product variant's prices set.
Prices are defined with a scope (currency and optionally country, CustomerGroup, and Channel and/or a validity period (validFrom and/or validTo).
For more information see price selection.
Adding a price is rejected:

if the product already contains a price with the same price scope (same currency, country, customer group, and channel).
if two prices have validity periods that overlap within the same price scope. A price without validity period does not conflict with a price defined for a time period.

A maximum number of 100 prices can be specified on a ProductVariant.

To keep the number of prices per Product Variant low, make use of the price selection fallback logic. For example, you can define a single price for all countries using the EUR currency instead of defining prices for the individual country attributes. Similarly, you can define a price without a channel attribute to use as a base price across channels, and create additional prices with a channel attribute for specific channels that differ from the base price.

action - String - "addPrice"
variantId - Number or sku - String - Required
price - PriceDraft - Required
staged - Boolean - Optional (Defaults to true)

Set Prices

Sets the prices of a product variant. The same validation rules as for addPrice apply. All previous price information is lost and even if some prices did not change, all the prices will have new IDs. A maximum number of 100 prices can be specified on a ProductVariant.

action - String - "setPrices"
variantId - Number or sku - String - Required
prices - Array of PriceDraft - Required
staged - Boolean - Optional (Defaults to true)

Change Price

Replaces a price in the product variant's prices set. The price to replace is specified by its ID.

action - String - "changePrice"
priceId - String - Required
ID of the Price
price - PriceDraft - Required
staged - Boolean - Optional (Defaults to true)

Remove Price

action - String - "removePrice"
priceId - String - Required
ID of the Price
staged - Boolean - Optional (Defaults to true)

Set Price Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing product price.

action - String - "setProductPriceCustomType"
type - ResourceIdentifier to a Type - Optional
If set, the custom type is set to this new value.
If absent, the custom type and any existing custom fields are removed.
priceId - String - Required
staged - Boolean - Optional (Defaults to true)
fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
If set, the CustomFields are set to this new value.

Set Price CustomField

This action sets, overwrites, or removes any existing custom field for an existing product price.

action - String - "setProductPriceCustomField"
priceId - String - Required
staged - Boolean - Optional (Defaults to true)
name - String - Required
value - Value - Optional
If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Set Discounted Price

Discounts a product price. The referenced ProductDiscount in the discounted field must be of type external, active, and its predicate must match the referenced price.

action - String - "setDiscountedPrice"
priceId - String - Required
staged - Boolean - Optional (Defaults to true)
discounted - DiscountedPrice - Optional

The set discounted value will be unset or replaced

when no discounted property is provided
once a matching relative or absolute product discount with a higher sortOrder exists,
if the referenced external discount is deactivated, or
if the product changes and the external product discount predicate does not match the discounted price any more.

Produces the ProductPriceExternalDiscountSet message.

Set Attribute

Adds/Removes/Changes a custom attribute.

action - String - "setAttribute"
variantId - Number or sku - String - Required
name - String - Required
value - * - Optional
If the attribute exists and the value is omitted or set to null, the attribute is removed. If the attribute exists and a value is provided, the new value is applied. If the attribute does not exist and a value is provided, it is added as a new attribute.
The AttributeType determines the format for the value to be provided, in particular:
- for EnumType and LocalizableEnumType attributes:
  - either only the key of the EnumValue or of the LocalizedEnumValue is to be used as value
  - or the complete EnumValue or the complete LocalizedEnumValue is to be used as value
- for LocalizableTextType attributes the LocalizedString object is to be used as value
- for MoneyType attributes the Money object is to be used as value
- for SetType attributes the entire set object is to be used as value
- for NestedType attributes the list of values of all attributes of the nested product is to be used as value
- for ReferenceType attributes the Reference object is to be used as value
staged - Boolean - Optional (Default is true)

Set Attribute In All Variants

Adds / Removes / Changes a custom attribute in all variants at the same time (it can be helpful to set attribute values that are constrained with SameForAll).

action - String - "setAttributeInAllVariants"
name - String - Required
value - * - Optional
The same update behavior as for Set Attribute applies.
staged - Boolean - Optional (Default is true)

Add to Category

action - String - "addToCategory"
category - ResourceIdentifier to a Category - Required
orderHint - String - Optional\
String representing a number which is greater than 0 and smaller than 1. It should start with 0. and should not end with 0. Valid examples: 0.1, 0.123456. Invalid examples: 0, 1, 0.10, 0.1234560, 0.12345e7.
staged - Boolean - Optional (Default is true)

Adding a product to a category produces the ProductAddedToCategory message.

Set Category Order Hint

action - String - "setCategoryOrderHint"
categoryId - Id of a Category the product belongs to - Required
orderHint - String - Optional (If left blank, the category order hint is unset/removed.)\
String representing a number which is greater than 0 and smaller than 1. It should start with 0. and should not end with 0. Valid examples: 0.1, 0.123456. Invalid examples: 0, 1, 0.10, 0.1234560, 0.12345e7.
staged - Boolean - Optional (Default is true)

Remove from Category

action - String - "removeFromCategory"
category - ResourceIdentifier to a Category - Required
staged - Boolean - Optional (Default is true)

Removing a product from a category produces the ProductRemovedFromCategory message.

Set TaxCategory

Adds, changes, or removes a product's TaxCategory. This change can never be staged and is thus immediately visible in published products.

action - String - "setTaxCategory"
taxCategory - ResourceIdentifier to a TaxCategory - Optional
If left blank or set to null, the tax category is unset/removed.

Set SKU

Adds, changes, or removes a SKU on a product variant. A SKU can only be changed or removed from a variant through this operation if there is no inventory entry associated with that SKU.

action - String - "setSku"
variantId - Number
sku - String - Optional
SKU must be unique. If left blank or set to null, the SKU is unset/removed.
staged - Boolean - Optional (Defaults to true)

Set ProductVariant Key

Adds, changes, or removes a key on a product variant.

action - String - "setProductVariantKey"
variantId - Number or sku - String - Required
key - String - Optional
If left blank or set to null, the key is unset/removed.
staged - Boolean - Optional (Defaults to true)

Add External Image

Adds external image url with meta-information to the product variant.

action - String - "addExternalImage"
variantId - Number or sku - String - Required
image - Image - Required
staged - Boolean - Optional (Defaults to true)

Adding an external image produces the ProductImageAdded message.

Move Image To Position

Moves an image to a new position within a product variant.

action - String - "moveImageToPosition"
variantId - Number or sku - String - Required
imageUrl - String- Required
The URL of the image
position - Number - Required
staged - Boolean - Optional (Defaults to true)

Remove Image

Removes a product image and deletes it from the Content Delivery Network (it would not be deleted from the CDN in case of external image). Deletion from the CDN is not instant, which means the image file itself will stay available for some time after the deletion.

action - String - "removeImage"
variantId - Number or sku - String - Required
imageUrl - String- Required
The URL of the image.
staged - Boolean - Optional (Defaults to true)

Set Image Label

action - String - "setImageLabel"
variantId - Number or sku - String - Required
imageUrl - String - Required
The URL of the image.
label - String - Optional
The new image label. If left blank or set to null, the label is removed.
staged - Boolean - Optional (Defaults to true)

Add Asset

Adds an Asset.

action - String - "addAsset"
variantId - Number or sku - String - Required
position - Number - Optional
Position of the new asset inside the existing list (from 0 to the size of the list)
staged - Boolean - Optional (Default is true)
asset - AssetDraft

Remove Asset

Removes an Asset.

action - String - "removeAsset"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Default is true)
assetId - String or assetKey - String - Required

Set Asset Key

Set or remove the key of an Asset.

action - String - "setAssetKey"
variantId - Integer or sku - String - Required
staged - Boolean - Optional (Default is true)
assetId - String - Required
assetKey - String - Optional
User-defined identifier for the asset.
If left blank or set to null, the asset key is unset/removed.

Change Asset Order

Changes the order of the assets array. The new order is defined by listing the ids of the assets.

action - String - "changeAssetOrder"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Default is true)
assetOrder - Array of String - Must contain all asset ids.

Change Asset Name

action - String - "changeAssetName"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Default is true)
assetId - String or assetKey - String - Required
name - LocalizedString - Required

Set Asset Description

action - String - "setAssetDescription"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Default is true)
assetId - String or assetKey - String - Required
description - LocalizedString - Optional

Set Asset Tags

action - String - "setAssetTags"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Default is true)
assetId - String or assetKey - String - Required
tags - Array of String - Optional

Set Asset Sources

action - String - "setAssetSources"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Default is true)
assetId - String or assetKey - String - Required
sources - Array of AssetSource - Requires at least one entry

Set Asset Custom Type

This action sets, overwrites, or removes the custom type and fields for an existing Asset.

action - String - "setAssetCustomType"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Default is true)
assetId - String or assetKey - String - Required
type - ResourceIdentifier to a Type - Optional
If set, the custom type is set to this new value.
If absent, the custom type and any existing custom fields are removed.
fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
If set, the custom fields are set to this new value.

Set Asset Custom Field

This action sets, overwrites, or removes any existing custom field for an existing Asset.

action - String - "setAssetCustomField"
variantId - Number or sku - String - Required
staged - Boolean - Optional (Default is true)
assetId - String or assetKey - String - Required
name - String - Required
value - Value - Optional
If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Set SearchKeywords

action - String - "setSearchKeywords"
searchKeywords - SearchKeywords - Required
staged - Boolean - Optional (Default is true)

Set Meta Title

action - String - "setMetaTitle"
metaTitle - LocalizedString - Optional
staged - Boolean - Optional (Default is true)

Set Meta Description

action - String - "setMetaDescription"
metaDescription - LocalizedString - Optional
staged - Boolean - Optional (Default is true)

Set Meta Keywords

action - String - "setMetaKeywords"
metaKeywords - LocalizedString - Optional
staged - Boolean - Optional (Default is true)

Revert Staged Changes

Revert all changes, which were made to the staged version of a product and reset to the current version.

action - String - "revertStagedChanges"

Reverting staged changes produces the ProductRevertedStagedChanges message.

Revert Staged Variant Changes

Revert changes of a variant, which were made to the staged version of a product and reset to the current version.

action - String - "revertStagedVariantChanges"
variantId - Integer - Required

Publish

action - String - "publish"
`scope` - String - Optional - one of `"All"` (default) or `"Prices"`

Publishing a product produces the ProductPublished message.

Publish with scope "All"

Publishes a product, which causes the staged projection of the product to override the current projection. If the product is published for the first time, the current projection is created.

Publish with scope "Prices"

Publishes only the product prices.
Publishing the prices is only possible if the product is currently published.
All prices found on variants in the staged projection are published into variants found in the current projection with the same id.
Prices found on a staged variant that has no current projection are not published.
Prices found on a current variant that has no staged projection are unchanged.
The flag hasStagedChanges is updated according to whether the staged and the current projections still differ after the prices publishing.

Unpublish

Unpublishes a product, effectively deleting the current projection of the product, leaving only the staged projection. When a product is unpublished, it will no longer be included in query or search results issued with staged=false, since such results only include current projections.

action - String - "unpublish"

Unpublishing a product produces the ProductUnpublished message.

Transition State

Transition to a new state. If there is no state yet, the new state must be an initial state. If the existing state has transitions set, there must be a direct transition to the new state. If transitions is not set, no validation is performed. These validations can be turned off by setting the force parameter to true.

action - String - "transitionState"
state - Reference to a State
force - Boolean - Optional - Defaults to false

Transitioning the state of a product produces the ProductStateTransition message.

Upload a product image

Uploads a binary image file to a given product variant. The supported image formats are JPEG, PNG, and GIF.

Endpoint: /{projectKey}/products/{id}/images
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: Product

Headers:

Content-Type - one of "image/jpeg", "image/png" or "image/gif".

Query Parameters:

variant - Number or sku - String - Optional
The variant to which the image should be added. Defaults to the master variant if neither is given.
filename - String - Optional (Defaults to "img")
Name under which the image should be stored in the Content Delivery Network. The name doesn't need to be unique - see below. The filename should be URL-encoded.
staged - Boolean - Optional (Defaults to true)
Whether to update the staged or current projection of the product.

Body: The raw binary data.

An example using cURL:

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

This adds an Image to the variant with id = 2, in the staged projection of the product.

Since the parameter filename=detail.jpg was specified, the URL of the uploaded image will be for example https://{sphere-cdn}/detail-6xAq4Efp.jpg. If you don't specify a custom filename a random one will be chosen.

The uploaded image is available in several sizes.

Note that a 200 OK response with a Product is returned as soon as the Small version of the image has been uploaded to the CDN. The other sizes might not be available immediately after a response is returned but only after a short delay.

Note that file upload using Content-Type: multipart/form-data is currently not supported.

Uploading an image produces the ProductImageAdded message. The message will be produced as soon as the Small version of the image has been uploaded to the CDN.

Delete Product

To be able to delete a product this has to be unpublished upfront.

If price selection query parameters are provided, the selected prices will be added to the response.

Deleting a product produces the ProductDeleted message.

Delete Product by ID

Endpoint: /{projectKey}/products/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: Product
Query Parameters:

version - Number - Required
priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.

Delete Product by Key

Delete a product found by its Key.

Endpoint: /{projectKey}/products/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: Product
Query Parameters:

version - Number - Required
priceCurrency - String - Optional
The currency code compliant to ISO 4217. Enables price selection.
priceCountry - String - Optional
A two-digit country code as per ISO 3166-1 alpha-2. Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceCustomerGroup - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.
priceChannel - UUID - Optional
Enables price selection. Can only be used in conjunction with the priceCurrency parameter.