Queries and mutations for managing Variants in the platform.
Queries
Query Variants
| Arguments | |
|---|---|
whereString | |
sortArray of String | |
limitInt | |
offsetInt | |
productIdString | Queries with specified Product ID |
Get Variant
| Arguments | |
|---|---|
skuString | Queries for a current variant with specified SKU |
stagedSkuString | Queries for a staged variant with specified SKU |
idString | Queries with specified ID |
keyString | Queries with specified key |
Mutations
Create Variant
Update Variant
| Arguments | |
|---|---|
idString | Queries with specified ID |
keyString | Queries with specified key |
actionsArray of VariantUpdateAction | |
versionLong | |
Delete Variant
| Arguments | |
|---|---|
idString | Queries with specified ID |
keyString | Queries with specified key |
versionLong | |
Bulk update Variants
Output types
Variant
A Variant represents a single Variant with both current (published) and staged (draft) data. Variants are writable resources that support create, update, and delete operations.
productRef | Reference to the parent Product the Variant belongs to. |
product | Reference to the parent Product the Variant belongs to. |
variantIdInt | A unique, sequential identifier of the Variant within the parent Product. |
keyString | User-defined unique identifier of the Variant.
This is different from Product key. |
current | The current data of the Variant. |
staged | The staged data of the Variant. Only present if there are staged changes that differ from the current data. |
publishedBoolean | Whether the Variant is published, false if it is unpublished. |
idString | Unique identifier of the Variant. |
versionLong | Current version of the Variant. |
createdAt | Date and time (UTC) the Variant was initially created. |
lastModifiedAt | Date and time (UTC) the Variant was last updated. |
createdBy | IDs and references that created the Variant. |
lastModifiedBy | IDs and references that last modified the Variant. |
VariantData
Contains the actual data for a Variant in either current (published) or staged (draft) state.
skuString | User-defined unique SKU of the Variant. |
imagesArray of Image | Images of the Variant. |
attributesRawArray of RawAttribute | This field contains raw attributes data |
assetsArray of Asset | Media assets of the Variant. |
RawAttribute
nameString | |
valueJson | |
attributesRawArray of RawAttribute | BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta |
referencedResource | |
referencedResourceSetArray of ReferenceExpandable |
VariantQueryResult
VariantDeletionResult
variant | |
warningsArray of TypedWarning | Warnings produced while deleting the variant. Only available in the mutation response. |
TypedWarning
A non-fatal warning that occurred during a mutation.
code | Can be CannotChangeReservationExpiry, CannotCreateReservation, CannotUpdateReservation, DefaultVariantDeleted, General, ImageProcessingOngoing, or StoreSettingOngoing |
messageString |
TypedWarningCode
CannotChangeReservationExpiryCannotCreateReservationCannotUpdateReservationDefaultVariantDeletedGeneralImageProcessingOngoingStoreSettingOngoing
BulkUpdateVariantsResponse
successCountInt | |
failureCountInt | |
resultsArray of BulkUpdateVariantsItemResult |
BulkUpdateVariantsItemResult
status | Can be Success, or Fail |
resource | |
errorsArray of BulkUpdateVariantsItemError |
BulkUpdateVariantsItemStatus
SuccessFail
BulkUpdateVariantsResource
idString | |
versionLong |
BulkUpdateVariantsItemError
codeString | |
messageString |
Input types
VariantDraft
Draft for creating a new Variant. When a Variant is created, only the current version is set. The staged version is only set when the Variant is updated with different current and staged data.
keyString | User-defined unique identifier for the Variant. This field is optional, but we strongly recommend setting it. |
product | ResourceIdentifier of the Product the Variant belongs to. |
skuString | User-defined unique SKU of the Variant. |
attributesArray of ProductAttributeInput | Variant Attributes according to the respective AttributeDefinition. Default: [] |
assetsArray of AssetDraftInput | Media assets for the Variant. Default:[] |
imagesArray of ImageInput | Images for the Variant. Default:[] |
publishBoolean | Indicates whether the Variant is published.
If Default: true, the Variant will be immediately available in the current published state.false |
ProductAttributeInput
An input object used to define a ProductAttribute.
The value should be passed in a form of escaped JSON.
value:- FieldType
String:"\"This is a string\"" - FieldType
DateTimeType:"\"2018-10-12T14:00:00.000Z\"" - FieldType
Number:"4" - FieldType
Setwith an elementType ofString:"[\"This is a string\", \"This is another string\"]" - FieldType
Reference:"{\"id\": \"b911b62d-353a-4388-93ee-8d488d9af962\", \"typeId\": \"product\"}"
nameString | |
valueString | The value should be passed in a form of escaped JSON. Examples for
value:
|
AssetDraftInput
keyString | |
nameArray of LocalizedStringItemInputType | |
descriptionArray of LocalizedStringItemInputType | |
custom | |
sourcesArray of AssetSourceInput | |
tagsArray of String | |
type |
AssetSourceInput
uriString | |
keyString | |
dimensions | |
contentTypeString |
AssetDimensionsInput
widthInt | |
heightInt |
ImageInput
urlString | |
labelString | |
dimensions |
DimensionsInput
widthInt | |
heightInt |
VariantUpdateAction
publish | |
unpublish | |
removeStagedChanges | |
removeAsset | |
moveImageToPosition | |
addExternalImage | |
addAsset | |
changeAssetName | |
changeAssetOrder | |
removeImage | |
setAssets | |
setAttribute | |
setAttributes | |
setImageLabel | |
setImages | |
setKey | |
setSku | |
setAssetCustomField | |
setAssetCustomType | |
setAssetDescription | |
setAssetKey | |
setAssetSources | |
setAssetTags |
BulkUpdateVariantsInput
itemsArray of BulkUpdateVariantsItemInput | |
actionsArray of VariantBulkAction | |
versionControl | Can be On, or OffDefault: On |
BulkUpdateVariantsItemInput
idString | |
keyString | |
versionLong |
VersionControl
OnOff
VariantBulkAction
publish | |
unpublish |
Update actions
Publish
dummyString |
Unpublish
dummyString |
Remove Staged Changes
dummyString |
Remove Asset
assetId or assetKey.assetIdString | The id of the Asset to remove. |
assetKeyString | The key of the Asset to remove. |
stagedBoolean | Whether only the staged Asset is removed. If Default: false, both the current and staged Asset is removed.true |
Move Image To Position
imageUrlString | |
positionInt | |
stagedBoolean | Default: true |
Add External Image
image | Value to add to images. |
stagedBoolean | Whether only the staged Default: images is updated. If false, both the current and staged images are updated.true |
ImageInput
urlString | |
labelString | |
dimensions |
DimensionsInput
widthInt | |
heightInt |
Add Asset
Adds an asset to existing variant's assets.
stagedBoolean | Whether only the staged Default: assets are updated. If false, both the current and staged assets are updated.true |
positionInt | Position in assets where the Asset should be put. When specified, the value must be between 0 and the total number of Assets minus 1. |
asset | Value to append. |
AssetDraftInput
keyString | |
nameArray of LocalizedStringItemInputType | |
descriptionArray of LocalizedStringItemInputType | |
custom | |
sourcesArray of AssetSourceInput | |
tagsArray of String | |
type |
AssetSourceInput
uriString | |
keyString | |
dimensions | |
contentTypeString |
AssetDimensionsInput
widthInt | |
heightInt |
Change Asset Name
assetId or assetKey.stagedBoolean | Whether only the staged Asset is updated. If Default: false, both the current and staged Asset is updated.true |
nameArray of LocalizedStringItemInputType | New value to set. Must not be empty. |
assetKeyString | The key of the Asset to update. |
assetIdString | The id of the Asset to update. |
Change Asset Order
Changes the order of Assets on a Variant.
stagedBoolean | Whether only the staged Default: assets is updated. If false, both the current and staged assets are updated.true |
assetOrderArray of String | All existing Asset ids of the Variant in the desired new order. |
Remove Image
Removes a Variant's image.
imageUrlString | The URL of the image to remove. |
stagedBoolean | Whether only the staged image is removed. If Default: false, both the current and staged image is removed.true |
Set Assets
Sets the assets of the Variant. Existing assets will be replaced with the new ones.
assetsArray of AssetDraftInput | Assets to set for the Variant. Default:[] |
stagedBoolean | Whether only the staged assets are set. If Default: false, both the current and staged assets are updated.true |
AssetDraftInput
keyString | |
nameArray of LocalizedStringItemInputType | |
descriptionArray of LocalizedStringItemInputType | |
custom | |
sourcesArray of AssetSourceInput | |
tagsArray of String | |
type |
AssetSourceInput
uriString | |
keyString | |
dimensions | |
contentTypeString |
AssetDimensionsInput
widthInt | |
heightInt |
Set Attribute
Set a specific Variant attribute.
nameString | Name of the Attribute to set. |
valueString | Value to set for the Attribute. If omitted, any existing value is removed. The AttributeType determines the format of the Attribute
value to be provided:
|
stagedBoolean | Whether only the staged Attribute is set. If Default: false, both the current and staged Attributes are set.true |
Set Attributes
Sets the attributes of the Variant. Existing attributes will be replaced with the new ones.
attributesArray of ProductAttributeInput | Attributes to set for the Variant according to the respective AttributeDefinition. Default: [] |
stagedBoolean | Whether only the staged attributes are updated. If Default: false, both the current and staged attributes are updated.true |
ProductAttributeInput
An input object used to define a ProductAttribute.
The value should be passed in a form of escaped JSON.
value:- FieldType
String:"\"This is a string\"" - FieldType
DateTimeType:"\"2018-10-12T14:00:00.000Z\"" - FieldType
Number:"4" - FieldType
Setwith an elementType ofString:"[\"This is a string\", \"This is another string\"]" - FieldType
Reference:"{\"id\": \"b911b62d-353a-4388-93ee-8d488d9af962\", \"typeId\": \"product\"}"
nameString | |
valueString | The value should be passed in a form of escaped JSON. Examples for
value:
|
Set Image Label
Sets the label of a Variant's image.
imageUrlString | The URL of the image to set the label. |
labelString | Value to set. If omitted, any existing value is removed. |
stagedBoolean | If Default: true, only the staged image is updated. If false, both the current and staged image is updated.true |
Set Images
imagesArray of ImageInput | Images to set for the Variant. Default:[] |
stagedBoolean | Whether only the staged images are updated. If Default: false, both the current and staged images are updated.true |
ImageInput
urlString | |
labelString | |
dimensions |
DimensionsInput
widthInt | |
heightInt |
Set Key
keyString | Value to set. Must be unique. |
Set SKU
skuString | Value to set. Must be unique. |
stagedBoolean | Whether only the staged Default: sku is updated. If false, both the current and staged sku are updated.true |
Set Asset Custom Field
assetId or assetKey.stagedBoolean | Whether only the staged Asset is updated. If Default: false, both the current and staged Asset is updated.true |
valueString | If value is absent or null, this field will be removed if it exists.
Removing a field that does not exist returns an InvalidOperation error.
If value is provided, it is set for the field defined by name. |
nameString | Name of the Custom Field. |
assetKeyString | The key of the Asset to update. |
assetIdString | The id of the Asset to update. |
Set Asset Custom Type
stagedBoolean | Default: true |
typeIdString | |
typeKeyString | |
type | |
fieldsArray of CustomFieldInput | |
assetKeyString | |
assetIdString |
Set Asset Description
assetId or assetKey.stagedBoolean | Whether only the staged Asset is updated. If Default: false, both the current and staged Asset is updated.true |
descriptionArray of LocalizedStringItemInputType | Value to set. If omitted, any existing value is removed. |
assetKeyString | The key of the Asset to update. |
assetIdString | The id of the Asset to update. |
Set Asset Key
Sets the key of an existing Asset on a Variant.
stagedBoolean | Whether only the staged Asset is updated. If Default: false, both the current and staged Asset is updated.true |
assetKeyString | Value to set. If omitted, any existing value is removed. |
assetIdString | The id of the Asset to update. |
Set Asset Sources
assetId or assetKey.stagedBoolean | Whether only the staged Asset is updated. If Default: false, both the current and staged Asset is updated.true |
sourcesArray of AssetSourceInput | Value to set. Default:[] |
assetKeyString | The key of the Asset to update. |
assetIdString | The id of the Asset to update. |
AssetSourceInput
uriString | |
keyString | |
dimensions | |
contentTypeString |
AssetDimensionsInput
widthInt | |
heightInt |