Products

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

Representations

Product

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

ProductCatalogData

ProductData

ProductVariant

ProductVariantAvailability

Price

DiscountedPrice

ScopedPrice

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

ProductDraft

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

ProductVariantDraft

PriceDraft

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 query parameter and a matching price exists, a price field containing the matching price is added to the ProductVariant of the returned product projections.

Attribute

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 within the interval (0…1) - whereby 1 is to be interpreted as the highest, and 0 as the lowest order score.
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 ↗ Admin Center EU (or ↗ Admin Center US ). 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 simply 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:

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

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

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.

Custom Tokenizer

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

Get Product

Get Product by ID

Gets the full representation of a product by ID.

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

Example Request
#!/bin/sh
$curl "https://api.sphere.io/{projectKey}/products/e7ba4c75-b1bb-483d-94d8-2c4a10f78472" \
  -H "Authorization: Bearer YrT7pRnLXVIco7KHlere_X-HL0sWdWOE"
Example Response
{
  "catalogData": {},
  "catalogs": [],
  "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
  "lastVariantId": 1,
  "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://sphere.io/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://sphere.io/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
OAuth2 Scopes: view_products:{projectKey}
Response Representation: Product
Query Parameters:

Query Products

You can use the query endpoint to get the full representations of products. REMARK: 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
OAuth2 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results array of Product
Query Parameters:

Example Request
#!/bin/sh
$curl "https://api.sphere.io/{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 Response
{
  "count": 1,
  "offset": 0,
  "results": [
    {
      "catalogData": {},
      "catalogs": [],
      "id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
      "lastVariantId": 1,
      "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://sphere.io/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://sphere.io/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
OAuth2 Scopes: manage_products:{projectKey}
Request Representation: ProductDraft
Response Representation: Product
Query Parameters:

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
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:

Fields:

Specific Error Codes:

Update Product by Key

Update a product found by its Key.

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

Fields:

Specific Error Codes:

Update Actions
Please find below the individual update actions provided on this endpoint.


Set Key

Change Name

Set Description

Change Slug

Changing the slug produces the ProductSlugChanged message.

Add ProductVariant

Remove ProductVariant

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.

Add Price

Adds the given price to the product variant’s prices set.
Prices are defined with a scope (currency, country, CustomerGroup and channel) and/or a validity period (validFrom and/or validTo).
A price without validity period (no validFrom and no validUntil) is always valid for its scope.
Adding a price is rejected:

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.

Change Price

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

Remove Price

Set Price Custom Type

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

Set Price CustomField

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

Set Discounted Price

Discounts a product price. The referenced Product Discount in the discounted field must be active, valid, of type external and it’s predicate must match the referenced price.

The set discounted value will be unset or replaced

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

Add to Category

Set Category Order Hint

Remove from Category

Set TaxCategory

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

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.

Set ProductVariant Key

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

Add External Image

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

Move Image To Position

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

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.

Add Asset

Adds an Asset.

Remove Asset

Removes an Asset.

Change Asset Order

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

Change Asset Name

Set Asset Description

Set Asset Tags

Set Asset Sources

Set Asset Custom Type

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

Set Asset Custom Field

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

Set SearchKeywords

Set Meta Title

Set Meta Description

Set Meta Keywords

Revert Staged Changes

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

Publish

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.

Publishing a product produces the ProductPublished message.

Unpublish

Unpublishes a product, effectively deleting the current projection of the product, leaving only the staged projection. Consequently, 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.

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.

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
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: Product

Headers:

Query Parameters:

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.sphere.io/{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 e.g. 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.

Delete Product

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

Delete Product by ID

Endpoint: /{projectKey}/products/{id}
Method: DELETE
OAuth2 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
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: Product
Query Parameters:

comments powered by Disqus