Queries and mutations for managing Variants in the platform.

Queries

Query Variants

QUERYvariants
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​
productId​
String​

Queries with specified Product ID

Get Variant

QUERYvariant
Arguments
sku​
String​

Queries for a current variant with specified SKU

stagedSku​
String​

Queries for a staged variant with specified SKU

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Variant

Mutations

Create Variant

MUTATIONcreateVariant
Arguments
draft​
Output:Variant

Update Variant

MUTATIONupdateVariant
Arguments
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

actions​
version​
Long​
Output:Variant

Delete Variant

MUTATIONdeleteVariant
Arguments
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

version​
Long​

Bulk update Variants

MUTATIONbulkUpdateVariants
Arguments
input​

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.
variantId​
Int​

A unique, sequential identifier of the Variant within the parent Product.

key​
String​
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.

published​
Boolean​
Whether the Variant is published, false if it is unpublished.
id​
String​

Unique identifier of the Variant.

version​
Long​

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.

sku​
String​

User-defined unique SKU of the Variant.

images​
Array of Image​

Images of the Variant.

attributesRaw​
Array of RawAttribute​

This field contains raw attributes data

assets​
Array of Asset​

Media assets of the Variant.

RawAttribute

name​
String​
value​
Json​
attributesRaw​
Array 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​
referencedResourceSet​

VariantQueryResult

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of Variant​

VariantDeletionResult

variant​
warnings​
Array of TypedWarning​

Warnings produced while deleting the variant. Only available in the mutation response.

TypedWarning

A non-fatal warning that occurred during a mutation.

Can be CannotChangeReservationExpiry, CannotCreateReservation, CannotUpdateReservation, DefaultVariantDeleted, General, ImageProcessingOngoing, or StoreSettingOngoing​
message​
String​

TypedWarningCode

CannotChangeReservationExpiry
CannotCreateReservation
CannotUpdateReservation
DefaultVariantDeleted
General
ImageProcessingOngoing
StoreSettingOngoing

BulkUpdateVariantsResponse

successCount​
Int​
failureCount​
Int​
results​

BulkUpdateVariantsItemResult

Can be Success, or Fail​
resource​
errors​

BulkUpdateVariantsItemStatus

Success
Fail

BulkUpdateVariantsResource

id​
String​
version​
Long​

BulkUpdateVariantsItemError

code​
String​
message​
String​

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.

key​
String​

User-defined unique identifier for the Variant. This field is optional, but we strongly recommend setting it.

ResourceIdentifier of the Product the Variant belongs to.
sku​
String​

User-defined unique SKU of the Variant.

attributes​
Variant Attributes according to the respective AttributeDefinition.
Default: []​
assets​
Array of AssetDraftInput​

Media assets for the Variant.

Default: []​
images​
Array of ImageInput​

Images for the Variant.

Default: []​
publish​
Boolean​
Indicates whether the Variant is published. If true, the Variant will be immediately available in the current published state.
Default: false​

ProductAttributeInput

An input object used to define a ProductAttribute.

The value should be passed in a form of escaped JSON.

Examples for value:
  • FieldType String: "\"This is a string\""
  • FieldType DateTimeType: "\"2018-10-12T14:00:00.000Z\""
  • FieldType Number: "4"
  • FieldType Set with an elementType of String: "[\"This is a string\", \"This is another string\"]"
  • FieldType Reference: "{\"id\": \"b911b62d-353a-4388-93ee-8d488d9af962\", \"typeId\": \"product\"}"
name​
String​
value​
String​

The value should be passed in a form of escaped JSON.

Examples for value:
  • FieldType String: "\"This is a string\""
  • FieldType DateTimeType: "\"2018-10-12T14:00:00.000Z\""
  • FieldType Number: "4"
  • FieldType Set with an elementType of String: "[\"This is a string\", \"This is another string\"]"
  • FieldType Reference: "{\"id\": \"b911b62d-353a-4388-93ee-8d488d9af962\", \"typeId\": \"product\"}"

AssetDraftInput

key​
String​
name​
description​
custom​
sources​
Array of AssetSourceInput​
tags​
Array of String​

AssetSourceInput

uri​
String​
key​
String​
dimensions​
contentType​
String​

AssetDimensionsInput

width​
Int​
height​
Int​

ImageInput

url​
String​
label​
String​
dimensions​

DimensionsInput

width​
Int​
height​
Int​

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

items​
actions​
Array of VariantBulkAction​
versionControl​
Can be On, or Off​Default: On​

BulkUpdateVariantsItemInput

id​
String​
key​
String​
version​
Long​

VersionControl

On
Off

VariantBulkAction

publish​
unpublish​

Update actions

Publish

dummy​
String​

Unpublish

dummy​
String​

Remove Staged Changes

dummy​
String​

Remove Asset

Removes an asset from an existing Variant's assets. The asset to remove must be specified using either assetId or assetKey.
assetId​
String​
The id of the Asset to remove.
assetKey​
String​
The key of the Asset to remove.
staged​
Boolean​
Whether only the staged Asset is removed. If false, both the current and staged Asset is removed.
Default: true​

Move Image To Position

imageUrl​
String​
position​
Int​
staged​
Boolean​
Default: true​

Add External Image

Adds an image to existing variant's images. Generates the VariantImageAdded Message.
image​
Value to add to images.
staged​
Boolean​
Whether only the staged images is updated. If false, both the current and staged images are updated.
Default: true​

ImageInput

url​
String​
label​
String​
dimensions​

DimensionsInput

width​
Int​
height​
Int​

Add Asset

Adds an asset to existing variant's assets.

staged​
Boolean​
Whether only the staged assets are updated. If false, both the current and staged assets are updated.
Default: true​
position​
Int​
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

key​
String​
name​
description​
custom​
sources​
Array of AssetSourceInput​
tags​
Array of String​

AssetSourceInput

uri​
String​
key​
String​
dimensions​
contentType​
String​

AssetDimensionsInput

width​
Int​
height​
Int​

Change Asset Name

Changes the name of an existing Asset on a Variant. The Asset to update must be specified using either assetId or assetKey.
staged​
Boolean​
Whether only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
name​

New value to set. Must not be empty.

assetKey​
String​
The key of the Asset to update.
assetId​
String​
The id of the Asset to update.

Change Asset Order

Changes the order of Assets on a Variant.

staged​
Boolean​
Whether only the staged assets is updated. If false, both the current and staged assets are updated.
Default: true​
assetOrder​
Array of String​
All existing Asset ids of the Variant in the desired new order.

Remove Image

Removes a Variant's image.

imageUrl​
String​

The URL of the image to remove.

staged​
Boolean​
Whether only the staged image is removed. If false, both the current and staged image is removed.
Default: true​

Set Assets

Sets the assets of the Variant. Existing assets will be replaced with the new ones.

assets​
Array of AssetDraftInput​

Assets to set for the Variant.

Default: []​
staged​
Boolean​
Whether only the staged assets are set. If false, both the current and staged assets are updated.
Default: true​

AssetDraftInput

key​
String​
name​
description​
custom​
sources​
Array of AssetSourceInput​
tags​
Array of String​

AssetSourceInput

uri​
String​
key​
String​
dimensions​
contentType​
String​

AssetDimensionsInput

width​
Int​
height​
Int​

Set Attribute

Set a specific Variant attribute.

name​
String​

Name of the Attribute to set.

value​
String​

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:
staged​
Boolean​
Whether only the staged Attribute is set. If false, both the current and staged Attributes are set.
Default: true​

Set Attributes

Sets the attributes of the Variant. Existing attributes will be replaced with the new ones.

attributes​
Attributes to set for the Variant according to the respective AttributeDefinition.
Default: []​
staged​
Boolean​
Whether only the staged attributes are updated. If false, both the current and staged attributes are updated.
Default: true​

ProductAttributeInput

An input object used to define a ProductAttribute.

The value should be passed in a form of escaped JSON.

Examples for value:
  • FieldType String: "\"This is a string\""
  • FieldType DateTimeType: "\"2018-10-12T14:00:00.000Z\""
  • FieldType Number: "4"
  • FieldType Set with an elementType of String: "[\"This is a string\", \"This is another string\"]"
  • FieldType Reference: "{\"id\": \"b911b62d-353a-4388-93ee-8d488d9af962\", \"typeId\": \"product\"}"
name​
String​
value​
String​

The value should be passed in a form of escaped JSON.

Examples for value:
  • FieldType String: "\"This is a string\""
  • FieldType DateTimeType: "\"2018-10-12T14:00:00.000Z\""
  • FieldType Number: "4"
  • FieldType Set with an elementType of String: "[\"This is a string\", \"This is another string\"]"
  • FieldType Reference: "{\"id\": \"b911b62d-353a-4388-93ee-8d488d9af962\", \"typeId\": \"product\"}"

Set Image Label

Sets the label of a Variant's image.

imageUrl​
String​

The URL of the image to set the label.

label​
String​

Value to set. If omitted, any existing value is removed.

staged​
Boolean​
If true, only the staged image is updated. If false, both the current and staged image is updated.
Default: true​

Set Images

Sets the images of the Variant. Existing images will be replaced with the new ones. Generates the VariantImagesSet Message.
images​
Array of ImageInput​

Images to set for the Variant.

Default: []​
staged​
Boolean​
Whether only the staged images are updated. If false, both the current and staged images are updated.
Default: true​

ImageInput

url​
String​
label​
String​
dimensions​

DimensionsInput

width​
Int​
height​
Int​

Set Key

Sets the key of the Variant. Generates the VariantKeySet Message.
key​
String​

Value to set. Must be unique.

Set SKU

Sets the SKU of the Variant. SKU cannot be changed or removed if it is associated with an InventoryEntry.
sku​
String​

Value to set. Must be unique.

staged​
Boolean​
Whether only the staged sku is updated. If false, both the current and staged sku are updated.
Default: true​

Set Asset Custom Field

Sets or removes a Custom Field on an existing Asset of a Variant. The Asset to update must be specified using either assetId or assetKey.
staged​
Boolean​
Whether only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
value​
String​
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.
name​
String​
Name of the Custom Field.
assetKey​
String​
The key of the Asset to update.
assetId​
String​
The id of the Asset to update.

Set Asset Custom Type

staged​
Boolean​
Default: true​
typeId​
String​
typeKey​
String​
fields​
Array of CustomFieldInput​
assetKey​
String​
assetId​
String​

Set Asset Description

Sets the description of an existing Asset on a Variant. The Asset to update must be specified using either assetId or assetKey.
staged​
Boolean​
Whether only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
description​

Value to set. If omitted, any existing value is removed.

assetKey​
String​
The key of the Asset to update.
assetId​
String​
The id of the Asset to update.

Set Asset Key

Sets the key of an existing Asset on a Variant.

staged​
Boolean​
Whether only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
assetKey​
String​

Value to set. If omitted, any existing value is removed.

assetId​
String​
The id of the Asset to update.

Set Asset Sources

Sets the sources of an existing Asset on a Variant. The Asset to update must be specified using either assetId or assetKey.
staged​
Boolean​
Whether only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
sources​
Array of AssetSourceInput​

Value to set.

Default: []​
assetKey​
String​
The key of the Asset to update.
assetId​
String​
The id of the Asset to update.

AssetSourceInput

uri​
String​
key​
String​
dimensions​
contentType​
String​

AssetDimensionsInput

width​
Int​
height​
Int​

Set Asset Tags

Sets the tags of an existing Asset on a Variant. The Asset to update must be specified using either assetId or assetKey.
staged​
Boolean​
Whether only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
tags​
Array of String​

Keywords for categorizing and organizing Assets.

Default: []​
assetKey​
String​
The key of the Asset to update.
assetId​
String​
The id of the Asset to update.