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.

Representations

Product

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

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

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

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.

  • 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 - Reference to an initial 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:

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

Note: 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” (i.e., 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 ↗ 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:

  • 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 e.g. 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 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, 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 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
OAuth2 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.
#!/bin/sh
$curl "https://api.sphere.io/{projectKey}/products/e7ba4c75-b1bb-483d-94d8-2c4a10f78472" \
  -H "Authorization: Bearer YrT7pRnLXVIco7KHlere_X-HL0sWdWOE"
{
  "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://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:

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

  • 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 not in arrays nested data e.g. 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.
#!/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"
{
  "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://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:

  • 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
OAuth2 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
OAuth2 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 Actions

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 - * - Optional
    If value is absent or null, this field will be removed if it exists.
    If value is provided, set the  value of the field defined by the name.
    The FieldDefinition determines the format for the value to be provided.
    In particular, for the fields definitions, value has to be provided as:

Set Discounted Price

Discounts a product price. The referenced ProductDiscount in the discounted field must be of type external, active and it’s 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:
  • 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 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 - * - Optional
    If value is absent or null, this field will be removed if it exists.
    If value is provided, set the  value of the field defined by the name.
    The FieldDefinition determines the format for the value to be provided.
    In particular, for the fields definitions, value has to be provided as:

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

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

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

In order 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
OAuth2 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
OAuth2 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.