Documentation

Products

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

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

Representations

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.
  • priceMode - ProductPriceMode - Optional BETA
    If not set, the Embedded ProductPriceMode is applied.

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

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 EmbeddedPrice - Optional
    The embedded 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 and it depends on the Product's priceMode value. 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 in response to a Product Projection Search with price selection. Can be used to sort, filter and facet.
  • 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.

EmbeddedPrice

ScopedPrice

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

ProductDraft

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

ProductResourceIdentifier

ResourceIdentifier to a Product.

  • id - String
    The unique ID of the referenced Product. Either id or key is required.
  • key - String
    The unique key of the referenced Product. Either id or key is required.
  • typeId - String - Optional
    If given, must be product.

ProductReference

Reference to a Product.

  • id - String - The unique ID of the referenced Product.
  • typeId - String - product

ProductVariantDraft

EmbeddedPriceDraft

ProductPriceMode BETA

This mode determines which type of Prices the API uses for Product Price Selection as well as for LineItem Price selection. This type can have one of the following values:

Changing the price mode does not change the behavior of the update actions Add Embedded Price, Set Embedded Prices, Change Embedded Price and Remove Embedded Price, which are only meant for managing EmbeddedPrices. Likewise the prices field in a ProductVariant contains only EmbeddedPrices regardless of the current price mode. Also, no migration from EmbeddedPrices to StandalonePrices or vice versa takes place when changing the price mode of a Product.

Price Selection

The cart addLineItem update action selects a price associated with the Product as indicated by priceMode and 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 EmbeddedPrice and StandalonePrice). 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\"".

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 commercetools Composable Commerce 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):

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:

Example RequestTerminal
#!/bin/sh
$curl "https://api.{region}.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:

Query Products

Querying on Product Attributes is discouraged as inefficient pattern. We recommend using the performance-optimized Search Product Projections endpoint instead whenever your use-case allows it.

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

Example RequestTerminal
#!/bin/sh
$curl "https://api.{region}.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
}

Query Product Selections for a Product BETA

Retrieves the Product Selections that contain the given Product.

Query Product Selections for a Product by Key

Endpoint: /{projectKey}/products/key={key}/product-selections
Method: GET
OAuth 2.0 Scopes: view_product_selections:{projectKey}
Response Representation: PagedQueryResult with results containing an array of AssignedProductSelection
Query Parameters:

Query Product Selections for a Product by ID

Endpoint: /{projectKey}/products/{id}/product-selections
Method: GET
OAuth 2.0 Scopes: view_product_selections:{projectKey}
Response Representation: PagedQueryResult with results containing an array of AssignedProductSelection
Query Parameters:

Check existence of Products

By Id

Endpoint: /{projectKey}/products/{id}
Method: HEAD
OAuth 2.0 Scopes: view_products:{projectKey}
Response Status: 200 OK if the product with given ID exists, 404 Not Found otherwise

By Key

Endpoint: /{projectKey}/products/key={key}
Method: HEAD
OAuth 2.0 Scopes: view_products:{projectKey}
Response Status: 200 OK if the product with given key exists, 404 Not Found otherwise

By Query Predicate

Endpoint: /{projectKey}/products
Method: HEAD
OAuth 2.0 Scopes: view_products:{projectKey}
Response Status: 200 OK if at least one product exists matching the query condition, 404 Not Found in case no product matches the query condition.
Query Parameters:

  • where - Query Predicate - Optional
    The predicate on product attributes is limited to text, enum, boolean, number, date, time and datetime attribute types.

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:

Creating a product produces the ProductCreatedMessage.

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:

Fields:

  • version - Number - Required
    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:

Fields:

  • version - Number - Required
    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 actions

Set Key
Change Name
Set Description
Change Slug
Add ProductVariant
Remove ProductVariant
Change Master Variant
Set PriceMode
Add Embedded Price
Set Embedded Prices
Change Embedded Price
Remove Embedded Price
Set Embedded Price Custom Type
Set Embedded Price CustomField
Set Discounted Embedded Price
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
Set Meta Title
Set Meta Description
Set Meta Keywords
Revert Staged Changes
Revert Staged Variant Changes
Publish
Publish with scope "All"
Publish with scope "Prices"
Unpublish
Transition State

Set Key

  • action - String - "setKey"
  • key - String - Optional
    If key is absent or null, the existing key, if any, will be removed.

Change Name

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

Set Description

  • action - String - "setDescription"
  • description - LocalizedString - Optional
    If the field already exists and the value is omitted or set to null, the field will be removed.
  • 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 ProductSlugChangedMessage.

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 EmbeddedPriceDraft - Optional. A maximum number of 100 prices can be specified on a ProductVariant. If you want to go over this limit, you can also use StandalonePrices for an alternative way for pricing your products.
  • images - Array of Image - Optional
    External images for the new variant. You can also upload images to use the Content Delivery Network of commercetools Composable Commerce.
  • 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 ProductVariantDeletedMessage.

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)

Set PriceMode BETA

Controls whether the Prices of a ProductVariant are embedded into the Product or stored as Standalone Price.

Add Embedded Price

Adds the given price to the set of prices of the product variant.
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, and channel).
  • 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.

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

Set Embedded Prices

Sets the Embedded Prices of a product variant. The same validation rules as for Add Embedded Price 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. If your business case requires going beyond this limit, use StandalonePrices instead.

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

Change Embedded Price

Replaces an Embedded 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 EmbeddedPrice
  • price - EmbeddedPriceDraft - Required
  • staged - Boolean - Optional (Defaults to true)

Remove Embedded Price

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

Set Embedded Price Custom Type

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

  • action - String - "setProductPriceCustomType"
  • type - ResourceIdentifier of 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 Embedded Price CustomField

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

  • action - String - "setProductPriceCustomField"
  • priceId - String - Required
  • staged - Boolean - Optional (Defaults to true)
  • name - String - Required
  • value - CustomFieldValue - 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 Embedded Price

Discounts a product's Embedded 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 - DiscountedPriceDraft - 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 ProductPriceExternalDiscountSetMessage.

Set Attribute

Adds/Removes/Changes a custom attribute.

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 of 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 ProductAddedToCategoryMessage.

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 of a Category - Required
  • staged - Boolean - Optional (Default is true)

Removing a product from a category produces the ProductRemovedFromCategoryMessage.

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 of 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 an 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 ProductImageAddedMessage.

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

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 - CustomFieldValue - 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 ProductRevertedStagedChangesMessage.

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

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

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

Upload a product image

Uploads a binary image file to a given product variant. The supported image formats are JPEG, PNG, and GIF. The file size of the image is limited to 10 MB.

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}.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 ProductImageAddedMessage. The message will be produced as soon as the Small version of the image has been uploaded to the CDN.

Images loaded on one product and then reused on another product or project may loose images when the original product is removed.

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

Delete Product by ID

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

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: