Products
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
- DateTimelastModifiedAt
- DateTimeproductType
- Reference to a ProductTypemasterData
- ProductCatalogData
The product data in the master catalog.taxCategory
- Reference to a TaxCategory - Optionalstate
- Reference to a State - OptionalreviewRatingStatistics
- ReviewRatingStatistics - Optional
Statistics about the review ratings taken into account for this product.
ProductCatalogData
published
- Boolean
Whether the product is published.current
- ProductData
The current data of the product.staged
- ProductData
The staged data of the product.-
hasStagedChanges
- Boolean
Whether the staged data is different from the current data.
ProductData
name
- LocalizedStringcategories
- Array of Reference to a Category
References to categories the product is in.categoryOrderHints
- CategoryOrderHints - Optionaldescription
- LocalizedString - Optionalslug
- LocalizedString
human-readable identifiers usually used as deep-link URL to the related product. Each slug is unique across a project, but a product can have the same slug for different languages.metaTitle
- LocalizedString - OptionalmetaDescription
- LocalizedString - OptionalmetaKeywords
- LocalizedString - OptionalmasterVariant
- ProductVariantvariants
- Array of ProductVariantsearchKeywords
- SearchKeywords
ProductVariant
-
id
- Number
The sequential ID of the variant within the product. -
sku
- String - Optional
The unique SKU of the variant. -
key
- String - Optional
User-specific unique identifier for the variant. Product variant keys are different from product keys. prices
- Array of Price - Optional
The prices of the variant. The prices does not contain two prices for the same price scope (same currency, country, customer group and channel).attributes
- Array of Attribute - Optionalprice
- Price - Optional
Only appears when price selection is used. This field cannot be used in a query predicate.images
- Array of Image - Optionalassets
- Array of Asset - Optionalavailability
- 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 - OptionalrestockableInDays
- 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
andquantityOnStock
are based on the Inventory Entry with no supply channel for this variant.channels
- Map of ProductVariantAvailability per Channelid
- Optional
For each Inventory Entries with a supply channel, an entry is added intochannels
:- the key is the Channel
id
- the value is an object containing the data
isOnStock
,restockableInDays
andavailableQuantity
for the Inventory Entry with the supply channel for this variant.
- the key is the Channel
Price
id
- String - read only
The unique ID of this price.value
- BaseMoneycountry
- String - Optional
A two-digit country code as per ↗ ISO 3166-1 alpha-2 .customerGroup
- Reference to a CustomerGroup - Optional
A reference to a customer group.channel
- Reference to a Channel - Optional
A reference to a channel.validFrom
- DateTime - Optional
Date from which the price is valid.validUntil
- DateTime - Optional
Date until which the price is valid.tiers
- Array of PriceTier - Optionaldiscounted
- DiscountedPrice - Optional
Set if a matching ProductDiscount exists. If set, the Cart will use the discounted value for the cart price calculation.
When a relative discount is applied and the fraction part of the discounted price is 0.5, the discounted price is rounded in favor of the customer with the half down rounding.custom
- CustomFields - Optional
PriceTier
A price tier is selected instead of the default price when a certain quantity of the ProductVariant is added to a cart and ordered.
For example: the price can be lower if more than 10 items are ordered.
If no price tier is found for the order quantity, the base Price is used.
A price tier is applied for the entire quantity of a product variant put as LineItem in a cart as soon as the minimum quantity for the price tier is reached.
The price tier is applied per line item of the product variant. If, for example, the same product variant appears in the same cart as several line items, (what can be achieved by different values of a custom field on the line items) for each line item the minimum quantity must be reached to get the price tier.
minimumQuantity
- Number
The minimum quantity this price tier is valid for.
The minimum quantity is always greater than or equal to 2 (the base Price is interpreted as valid for minimum quantity equals to 1).- value - BaseMoney
The currency of a price tier is always the same as the currency of the base Price.
DiscountedPrice
value
- Moneydiscount
- Reference to a ProductDiscount
ScopedPrice
Scoped price is returned as a part of a variant in product search (when price selector is used).
id
- String - read only
The unique ID of this price.value
- BaseMoney - the original price valuecurrentValue
- BaseMoney - either the original pricevalue
or thediscounted
value, if it’s availablecountry
- String - Optional
A two-digit country code as per ↗ ISO 3166-1 alpha-2 .customerGroup
- Reference to a CustomerGroup - Optional
A reference to a customer group.channel
- Reference to a Channel - Optional
A reference to a channel.validFrom
- DateTime - Optional
Date from which the price is valid.validUntil
- DateTime - Optional
Date until which the price is valid.discounted
- DiscountedPrice - Optional
Is set if a matching ProductDiscount exists. If set, the Cart will use the discounted value for the cart price calculation.
When a relative discount is applied and the fraction part of the discounted price is 0.5, the discounted price is rounded in favor of the customer with the half down rounding.custom
- CustomFields - Optional
ProductDraft
The representation sent to the server when creating a new product.
key
- String - Optional
User-specific unique identifier for the product.name
- LocalizedString - RequiredproductType
- 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 - Optionalcategories
- Array of ResourceIdentifier for a Category - Optional
Categories assigned to the product.categoryOrderHints
- CategoryOrderHints - OptionalmetaTitle
- LocalizedString - OptionalmetaDescription
- LocalizedString - OptionalmetaKeywords
- LocalizedString - OptionalmasterVariant
- ProductVariantDraft - Optional
The master product variant. Required if thevariants
array has product variants.variants
- Array of ProductVariantDraft - Optional
An array of related product variants.taxCategory
- ResourceIdentifier to a TaxCategory - OptionalsearchKeywords
- SearchKeywords - Optionalstate
- Reference to an initial State - Optionalpublish
- Boolean - Optional, defaults tofalse
Iftrue
, 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 specifiedimages
- 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 - Optionalattributes
- Array of Attribute - Optional
The AttributeType determines the format for the attributevalue
to be provided, in particular:- for EnumType and LocalizableEnumType attributes:
- either only the
key
of the EnumValue or of the LocalizedEnumValue is to be used asvalue
- or the complete EnumValue or the complete LocalizedEnumValue is to be used as
value
- either only the
- for LocalizableTextType attributes the LocalizedString object is to be used as
value
- for MoneyType attributes the Money object is to be used as
value
- for SetType attributes the entire
set
object is to be used asvalue
- for NestedType attributes the list of values of all attributes of the nested product is to be used as
value
- for ReferenceType attributes the Reference object is to be used as
value
- for EnumType and LocalizableEnumType attributes:
PriceDraft
value
- BaseMoney - Requiredcountry
- String - Optional
A two-digit country code as per ↗ ISO 3166-1 alpha-2 . If not set, the price is valid for any country.customerGroup
- Reference to a CustomerGroup - Optional
A reference to a customer group.channel
- ResourceIdentifier to a Channel - Optional
Connection to a particular channel.validFrom
- DateTime - Optional
Date from which the price is valid.validUntil
- DateTime - Optional
Date until which the price is valid.tiers
- Array of PriceTier - Optionalcustom
- CustomFieldsDraft - Optional
The custom fields.
Price Selection
The cart addLineItem update action selects a price from the product’s prices array based on the currency, country, customer group, channel and a date. The product-related endpoints also provide the same price selection logic to help the shop to show the right price to the customer.
If the price selection parameter priceCurrency
and any of the price selection parameters priceCountry
, priceCustomerGroup
and
priceChannel
are given as 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
name
- Stringvalue
- *
A valid JSON value, based on an AttributeDefinition.
Category Order Hints
Products can have a category order hint for each category they are assigned to. This allows controlling the order of products and how they appear in categories.
The category order hints is a JSON object where the keys are the category IDs, and the values are the corresponding order hint set for that category.
Order hints are strings representing valid number values between 0 and 1 while everything closer to 1 is interpreted as higher than everything closer to 0. Order hints thus always start with “0.” and must never end with a “0” (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):
-
-thumb
(50x50) - ↗ example -
-small
(150x150) - ↗ example -
-medium
(400x400) - ↗ example -
-large
(700x700) - ↗ example -
-zoom
(1400x1400) - ↗ example -
the original size of the uploaded image is provided without a suffix - ↗ example
Note that images will never be scaled up. If the original image is tiny, it will keep its original size, even in the “large” and “zoom” sizes.
Also note that images are not shared between variants - each variant has its own set of images. However, if you wish to have many variants with the same set of images, you can implement this in your application by always showing the images of the master variant, regardless of the selected variant.
SearchKeywords
Search keywords are primarily used by the suggester, but are also considered for the full text search. SearchKeywords is a JSON object where the keys are of ↗ IETF language tag . The value to a language tag key is an array of SearchKeyword for the specific language.
{ "en": [{"text": "Multi tool"}, {"text": "Swiss Army Knife", "suggestTokenizer": {"type": "whitespace"}}], "de": [{"text": "Schweizer Messer", "suggestTokenizer": {"type": "custom", "inputs": ["schweizer messer", "offiziersmesser", "sackmesser"]}}]}
SearchKeyword
text
- String
Text to return in the result of a suggest query.suggestTokenizer
- SuggestTokenizer - Optional
If no tokenizer is defined, thetext
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 thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.
#!/bin/sh$curl "https://api.sphere.io/{projectKey}/products/e7ba4c75-b1bb-483d-94d8-2c4a10f78472" \ -H "Authorization: Bearer YrT7pRnLXVIco7KHlere_X-HL0sWdWOE"
{ "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:
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 thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
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 totext
,enum
,boolean
,number
,date
,time
anddatetime
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 - Optionallimit
- Number - Optionaloffset
- Number - OptionalpriceCurrency
- 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 thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
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": [ { "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:
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 thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
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 thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
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 thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
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 tonull
, the product key is unset/removed.
Change Name
action
- String -"changeName"
name
- LocalizedString - Requiredstaged
- Boolean - Optional (Default:true
)
Set Description
action
- String -"setDescription"
description
- LocalizedString - Requiredstaged
- Boolean - Optional (Defaults totrue
)
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 totrue
)
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 fieldname
corresponds to the name of a product attribute defined on the referenced ProductType and thevalue
being a valid JSON value for that attribute.staged
- Boolean - Optional (Defaults totrue
)assets
- Array of Asset - Optional
Remove ProductVariant
action
- String -"removeVariant"
id
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Defaults totrue
)
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 orsku
- String - Requiredstaged
- Boolean - Optional (Defaults totrue
)
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 orsku
- String - Requiredprice
- PriceDraft - Requiredstaged
- Boolean - Optional (Defaults totrue
)
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 orsku
- String - Requiredprices
- Array of PriceDraft - Requiredstaged
- Boolean - Optional (Defaults totrue
)
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 Priceprice
- PriceDraft - Requiredstaged
- Boolean - Optional (Defaults totrue
)
Remove Price
action
- String -"removePrice"
priceId
- String - Required
ID of the Pricestaged
- Boolean - Optional (Defaults totrue
)
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 - Requiredstaged
- Boolean - Optional (Defaults totrue
)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 - Requiredstaged
- Boolean - Optional (Defaults totrue
)name
- String - Requiredvalue
- * - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists.
Ifvalue
is provided, set thevalue
of the field defined by thename
.
The FieldDefinition determines the format for thevalue
to be provided.
In particular, for the fields definitions,value
has to be provided as:- for EnumType and LocalizedEnumType fields: the
key
of the EnumValue or the LocalizedEnumValue - for LocalizedStringType fields: the LocalizedString object
- for MoneyType fields: the Money object
- for SetType fields: the entire
Set
object - for ReferenceType fields: the Reference object
- for EnumType and LocalizedEnumType fields: the
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 - Requiredstaged
- Boolean - Optional (Defaults totrue
)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 orsku
- String - Requiredname
- String - Requiredvalue
- * - Optional
If the attribute exists and the value is omitted or set tonull
, 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 thevalue
to be provided, in particular:- for EnumType and LocalizableEnumType attributes:
- either only the
key
of the EnumValue or of the LocalizedEnumValue is to be used asvalue
- or the complete EnumValue or the complete LocalizedEnumValue is to be used as
value
- either only the
- for LocalizableTextType attributes the LocalizedString object is to be used as
value
- for MoneyType attributes the Money object is to be used as
value
- for SetType attributes the entire
set
object is to be used asvalue
- for NestedType attributes the list of values of all attributes of the nested product is to be used as
value
- for ReferenceType attributes the Reference object is to be used as
value
- for EnumType and LocalizableEnumType attributes:
staged
- Boolean - Optional (Default istrue
)
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 - Requiredvalue
- * - Optional
The same update behavior as for Set Attribute applies.staged
- Boolean - Optional (Default istrue
)
Add to Category
action
- String -"addToCategory"
category
- ResourceIdentifier to a Category - RequiredorderHint
- 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 istrue
)
Set Category Order Hint
action
- String -"setCategoryOrderHint"
categoryId
- Id of a Category the product belongs to - RequiredorderHint
- 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 istrue
)
Remove from Category
action
- String -"removeFromCategory"
category
- ResourceIdentifier to a Category - Requiredstaged
- Boolean - Optional (Default istrue
)
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 tonull
, 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
- Numbersku
- String - Optional
SKU must be unique. If left blank or set tonull
, the sku is unset/removed.staged
- Boolean - Optional (Defaults totrue
)
Set ProductVariant Key
Adds, changes or removes a key on a product variant.
action
- String -"setProductVariantKey"
variantId
- Number orsku
- String - Requiredkey
- String - Optional
If left blank or set tonull
, the key is unset/removed.staged
- Boolean - Optional (Defaults totrue
)
Add External Image
Adds external image url with meta-information to the product variant.
action
- String -"addExternalImage"
variantId
- Number orsku
- String - Requiredimage
- Image - Requiredstaged
- Boolean - Optional (Defaults totrue
)
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 orsku
- String - RequiredimageUrl
- String- Required
The URL of the imageposition
- Number - Requiredstaged
- Boolean - Optional (Defaults totrue
)
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 orsku
- String - RequiredimageUrl
- String- Required
The URL of the image.staged
- Boolean - Optional (Defaults totrue
)
Set Image Label
action
- String -"setImageLabel"
variantId
- Number orsku
- String - RequiredimageUrl
- 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 totrue
)
Add Asset
Adds an Asset.
action
- String -"addAsset"
variantId
- Number orsku
- String - Requiredposition
- Number - Optional
Position of the new asset inside the existing list (from0
to the size of the list)staged
- Boolean - Optional (Default istrue
)asset
- AssetDraft
Remove Asset
Removes an Asset.
action
- String -"removeAsset"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Required
Set Asset Key
Set or remove the key
of an an Asset.
action
- String -"setAssetKey"
variantId
- Integer orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String - RequiredassetKey
- String - Optional
User-defined identifier for the asset.
If left blank or set tonull
, the asset key is unset/removed.
Change Asset Order
Changes the order of the assets
array. The new order is defined by listing the id
s of the assets.
action
- String -"changeAssetOrder"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetOrder
- Array of String - Must contain all assetid
s.
Change Asset Name
action
- String -"changeAssetName"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredname
- LocalizedString - Required
Set Asset Description
action
- String -"setAssetDescription"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requireddescription
- LocalizedString - Optional
Set Asset Tags
action
- String -"setAssetTags"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredtags
- Array of String - Optional
Set Asset Sources
action
- String -"setAssetSources"
variantId
- Number orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredsources
- 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 orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredtype
- 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 orsku
- String - Requiredstaged
- Boolean - Optional (Default istrue
)assetId
- String orassetKey
- String - Requiredname
- String - Requiredvalue
- * - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists.
Ifvalue
is provided, set thevalue
of the field defined by thename
.
The FieldDefinition determines the format for thevalue
to be provided.
In particular, for the fields definitions,value
has to be provided as:- for EnumType and LocalizedEnumType fields: the
key
of the EnumValue or the LocalizedEnumValue - for LocalizedStringType fields: the LocalizedString object
- for MoneyType fields: the Money object
- for SetType fields: the entire
Set
object - for ReferenceType fields: the Reference object
- for EnumType and LocalizedEnumType fields: the
Set SearchKeywords
action
- String -"setSearchKeywords"
searchKeywords
- SearchKeywords - Requiredstaged
- Boolean - Optional (Default istrue
)
Set Meta Title
action
- String -"setMetaTitle"
metaTitle
- LocalizedString - Optionalstaged
- Boolean - Optional (Default istrue
)
Set Meta Description
action
- String -"setMetaDescription"
metaDescription
- LocalizedString - Optionalstaged
- Boolean - Optional (Default istrue
)
Set Meta Keywords
action
- String -"setMetaKeywords"
metaKeywords
- LocalizedString - Optionalstaged
- Boolean - Optional (Default istrue
)
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
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 Stateforce
- Boolean - Optional - Defaults tofalse
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 orsku
- 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 totrue
)
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 - RequiredpriceCurrency
- 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 thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
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 - RequiredpriceCurrency
- 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 thepriceCurrency
parameter.priceCustomerGroup
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.priceChannel
- UUID - Optional
Enables price selection. Can only be used in conjunction with thepriceCurrency
parameter.