Variants

B2CB2BB2XBETA

Manage Variants independently from Products as a standalone entity.

Variants are writable resources that support create, update, and delete operations independently from their parent Products.

Each Variant contains current, published data. Staged (draft) data is only present when there are unpublished changes, allowing you to manage changes before publishing them. When you create a Variant, only the current version is created. When you update a Variant, you can choose to update either the current or staged data. When you publish a Variant, the staged data is copied to the current data.

A maximum number of 10 000 Variants per Product can be created. Learn more about this limit.
  • This endpoint is only available for Projects with productCatalogModel set to Modular.
  • In the Modular catalog model, pricing is exclusively handled through Standalone Prices. Embedded Prices are not supported, and the Project's price mode is fixed to Standalone.
  • To query read-only Variant data optimized for storefront display, use the Variant Projections API instead.

Representations

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.

id​
String​

Unique identifier of the Variant.

version​
Int​

Current version of the Variant.

key​
String​
User-defined unique identifier of the Variant. This is different from Product key.
variantId​
Int​

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

product​
ProductReference​
Reference to the parent Product the Variant belongs to.
published​
Boolean​
true if the Variant is published, false if it is unpublished.
current​
VariantData​

The current data of the Variant.

staged​
VariantData​

The staged data of the Variant. Only present if there are staged changes that differ from the current data.

createdAt​
DateTime​

Date and time (UTC) the Variant was initially created.

createdBy​BETA
CreatedBy​

IDs and references that created the Variant.

lastModifiedAt​
DateTime​

Date and time (UTC) the Variant was last updated.

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the Variant.

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.

sku​
String​

User-defined unique SKU of the Variant.

product​
ProductResourceIdentifier​
ResourceIdentifier of the Product the Variant belongs to.
publish​
Boolean​
Indicates whether the Variant is published. If true, the Variant will be immediately available in the current published state.
Default: false​
images​
Array of Image​

Images for the Variant.

attributes​
Array of Attribute​
Variant Attributes according to the respective AttributeDefinition.
assets​
Array of AssetDraft​

Media assets for the Variant.

VariantPagedQueryResponse

PagedQueryResult with results containing an array of Variant.
limit​
Int​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int​

Actual number of results returned.

total​
Int​
Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. Unless absolutely necessary, use the query parameter withTotal=false to improve performance by deactivating the calculation of this field. When the results are filtered with a Query Predicate, total is subject to a limit.
results​
Array of Variant​
Variants matching the query.

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.

attributes​
Array of Attribute​
Attributes of the Variant according to the respective AttributeDefinition.
assets​
Array of Asset​

Media assets of the Variant.

VariantBulkUpdate

The request body for a bulk update of Variants.

items​
Array of VariantBulkUpdateItem​
List of Variants to update. Each item must identify the Variant by id or key.
MaxItems: 1000​
actions​
Array of VariantUpdateAction​
The update action to apply to each Variant. Only Publish and Unpublish actions are supported. An empty array results in a no-op: all items are returned as successful with no changes applied.
MaxItems: 1​
Example: json
{
  "items": [
    {
      "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
      "version": 1
    },
    {
      "key": "my-variant-key",
      "version": 3
    }
  ],
  "actions": [
    {
      "action": "publish"
    }
  ]
}

VariantBulkUpdateItem

Identifies a single Variant to be updated in a bulk update request. Provide either id or key to identify the Variant.
id​
String​
Unique identifier of the Variant to update. Either id or key must be provided.
version​
Int​
Expected version of the Variant. Required when the versionControl query parameter is On (the default). If the version does not match, a ConcurrentModification error is returned for that item. Not required when versionControl=Off.
key​
String​
User-defined unique identifier of the Variant to update. Either id or key must be provided.
Example: json
{
  "key": "my-variant-key",
  "version": 1
}

VariantBulkUpdateResponse

The response body for a bulk update of Variants. Contains the individual result for each Variant in the request.

successCount​
Int​

Number of Variants that were successfully updated.

failureCount​
Int​

Number of Variants that failed to update.

results​
Array of VariantBulkUpdateResult​
Results for each Variant in the request, in the same order as the items in the request body.
Example: json
{
  "successCount": 1,
  "failureCount": 1,
  "results": [
    {
      "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
      "status": "Success",
      "resource": {
        "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
        "version": 2
      }
    },
    {
      "id": "2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
      "status": "Fail",
      "errors": [
        {
          "code": "ConcurrentModification",
          "message": "Object 2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f has a different version than expected. Expected: 0 - Actual: 3.",
          "currentVersion": 3
        }
      ]
    }
  ]
}

VariantBulkUpdateResult

Represents the result of a single Variant update within a bulk update request. Use status to determine whether the update succeeded or failed.
id​
String​
Unique identifier of the Variant from the request. Present when the Variant was identified by id.
key​
String​
User-defined unique identifier of the Variant from the request. Present when the Variant was identified by key.
status​
String​

Indicates whether the update succeeded or failed.

Can be "Success", or "Fail"​

VariantBulkUpdateSuccessResult

Result for a Variant that was successfully updated in a bulk update request.

id​
String​
Unique identifier of the Variant from the request. Present when the Variant was identified by id.
key​
String​
User-defined unique identifier of the Variant from the request. Present when the Variant was identified by key.
status​
String​
"Success"

Indicates whether the update succeeded or failed.

resource​
VariantBulkUpdateResource​
A lightweight reference containing the id and updated version of the Variant.
Example: json
{
  "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
  "status": "Success",
  "resource": {
    "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
    "version": 2
  }
}

VariantBulkUpdateResource

A lightweight reference containing the id and updated version of a Variant after a successful bulk update.
id​
String​

Unique identifier of the updated Variant.

version​
Int​

The new version of the Variant after the update.

Example: json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 2
}

VariantBulkUpdateFailResult

Result for a Variant that failed to update in a bulk update request.

id​
String​
Unique identifier of the Variant from the request. Present when the Variant was identified by id.
key​
String​
User-defined unique identifier of the Variant from the request. Present when the Variant was identified by key.
status​
String​
"Fail"

Indicates whether the update succeeded or failed.

errors​
Array of ErrorObject​

Errors that caused the update to fail for this Variant.

Example: json
{
  "id": "2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
  "status": "Fail",
  "errors": [
    {
      "code": "ConcurrentModification",
      "message": "Object 2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f has a different version than expected. Expected: 0 - Actual: 3.",
      "currentVersion": 3
    }
  ]
}

Get Variant

Get Variant by ID

GET
https://api.{region}.commercetools.com/{projectKey}/variants/{id}

Retrieves a Variant by its ID.

OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the Variant.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Variant

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/variants/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Variantjson
{
  "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
  "version": 2,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModifiedAt": "2024-01-16T14:20:00.000Z",
  "lastModifiedBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "key": "variant-blue-medium",
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "published": false,
  "current": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/variant-blue-medium.jpg",
        "label": "Blue Medium Variant",
        "dimensions": {
          "w": 800,
          "h": 600
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/variant-demo-video.mp4",
            "key": "demo-video"
          }
        ],
        "name": {
          "en-US": "Variant Demo Video",
          "de-DE": "Variant-Demonstrationsvideo"
        },
        "description": {
          "en-US": "Detailed demonstration of the variant features",
          "de-DE": "Detaillierte Demonstration der Variant-Merkmale"
        },
        "tags": ["video", "demo", "tutorial"]
      }
    ]
  },
  "staged": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/product-blue-medium-updated.jpg",
        "label": "Blue Medium Variant - Updated",
        "dimensions": {
          "w": 1200,
          "h": 900
        }
      },
      {
        "url": "https://example.com/images/product-blue-medium-detail.jpg",
        "label": "Blue Medium Variant - Detail",
        "dimensions": {
          "w": 1200,
          "h": 900
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      },
      {
        "name": "material",
        "value": "cotton"
      },
      {
        "name": "weight",
        "value": 250
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/product-video-v2.mp4",
            "key": "product-video-v2"
          }
        ],
        "name": {
          "en-US": "Product Video - Updated",
          "de-DE": "Produktvideo - Aktualisiert",
          "fr-FR": "Vidéo du produit - Mise à jour",
          "es-ES": "Video del producto - Actualizado"
        },
        "description": {
          "en-US": "Updated product demonstration video with new features",
          "de-DE": "Aktualisiertes Produktdemonstrationsvideo mit neuen Funktionen",
          "fr-FR": "Vidéo de démonstration mise à jour avec de nouvelles fonctionnalités",
          "es-ES": "Video de demostración actualizado con nuevas características"
        },
        "tags": ["video", "demo", "updated"]
      }
    ]
  }
}

Get Variant by Key

GET
https://api.{region}.commercetools.com/{projectKey}/variants/key={key}

Retrieves a Variant by its key.

OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the Variant.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Variant

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/variants/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Variantjson
{
  "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
  "version": 2,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModifiedAt": "2024-01-16T14:20:00.000Z",
  "lastModifiedBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "key": "variant-blue-medium",
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "published": false,
  "current": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/variant-blue-medium.jpg",
        "label": "Blue Medium Variant",
        "dimensions": {
          "w": 800,
          "h": 600
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/variant-demo-video.mp4",
            "key": "demo-video"
          }
        ],
        "name": {
          "en-US": "Variant Demo Video",
          "de-DE": "Variant-Demonstrationsvideo"
        },
        "description": {
          "en-US": "Detailed demonstration of the variant features",
          "de-DE": "Detaillierte Demonstration der Variant-Merkmale"
        },
        "tags": ["video", "demo", "tutorial"]
      }
    ]
  },
  "staged": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/product-blue-medium-updated.jpg",
        "label": "Blue Medium Variant - Updated",
        "dimensions": {
          "w": 1200,
          "h": 900
        }
      },
      {
        "url": "https://example.com/images/product-blue-medium-detail.jpg",
        "label": "Blue Medium Variant - Detail",
        "dimensions": {
          "w": 1200,
          "h": 900
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      },
      {
        "name": "material",
        "value": "cotton"
      },
      {
        "name": "weight",
        "value": 250
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/product-video-v2.mp4",
            "key": "product-video-v2"
          }
        ],
        "name": {
          "en-US": "Product Video - Updated",
          "de-DE": "Produktvideo - Aktualisiert",
          "fr-FR": "Vidéo du produit - Mise à jour",
          "es-ES": "Video del producto - Actualizado"
        },
        "description": {
          "en-US": "Updated product demonstration video with new features",
          "de-DE": "Aktualisiertes Produktdemonstrationsvideo mit neuen Funktionen",
          "fr-FR": "Vidéo de démonstration mise à jour avec de nouvelles fonctionnalités",
          "es-ES": "Video de demostración actualizado con nuevas características"
        },
        "tags": ["video", "demo", "updated"]
      }
    ]
  }
}

Query Variants

When querying an Attribute, we recommend that you use the performance-optimized Variant Projections API whenever possible. For more information, see inefficient patterns.
GET
https://api.{region}.commercetools.com/{projectKey}/variants

Queries Variants matching the provided predicates. This endpoint returns both current (published) and staged (draft) data for each Variant.

When querying an Attribute, you must always include both the attribute-name and attribute-value details in the QueryPredicate. Otherwise, a 400 Bad Request error will occur.
OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
QueryPredicate
​
Query Predicates on Attributes are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

VariantPagedQueryResponse

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/variants -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: VariantPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
      "version": 1,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "lastModifiedAt": "2024-01-15T10:30:00.000Z",
      "lastModifiedBy": {
        "clientId": "abc123xyz789",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "abc123xyz789",
        "isPlatformClient": false
      },
      "key": "variant-blue-medium",
      "variantId": 2,
      "product": {
        "typeId": "product",
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
      },
      "published": true,
      "current": {
        "sku": "SKU-BLUE-M-001",
        "images": [
          {
            "url": "https://example.com/images/product-blue-medium.jpg",
            "label": "Blue Medium Variant",
            "dimensions": {
              "w": 800,
              "h": 600
            }
          }
        ],
        "attributes": [
          {
            "name": "color",
            "value": "blue"
          },
          {
            "name": "size",
            "value": "M"
          }
        ],
        "assets": [
          {
            "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
            "sources": [
              {
                "uri": "https://example.com/assets/product-blue-video.mp4",
                "key": "product-blue-video"
              }
            ],
            "name": {
              "en-US": "Blue Variant Video",
              "de-DE": "Blaue Variante Video"
            },
            "description": {
              "en-US": "Product demonstration video for blue variant",
              "de-DE": "Produktdemonstrationsvideo für blaue Variante"
            },
            "tags": ["video", "blue", "medium"]
          }
        ]
      }
    },
    {
      "id": "8b4c6d9e-2f3a-5b6c-9d0e-1f2a3b4c5d6e",
      "version": 1,
      "createdAt": "2024-01-15T11:00:00.000Z",
      "lastModifiedAt": "2024-01-15T11:00:00.000Z",
      "lastModifiedBy": {
        "clientId": "abc123xyz789",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "abc123xyz789",
        "isPlatformClient": false
      },
      "key": "variant-red-large",
      "variantId": 3,
      "product": {
        "typeId": "product",
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
      },
      "published": true,
      "current": {
        "sku": "SKU-RED-L-002",
        "images": [
          {
            "url": "https://example.com/images/product-red-large.jpg",
            "label": "Red Large Variant",
            "dimensions": {
              "w": 800,
              "h": 600
            }
          }
        ],
        "attributes": [
          {
            "name": "color",
            "value": "red"
          },
          {
            "name": "size",
            "value": "L"
          }
        ],
        "assets": [
          {
            "id": "8e7d6c5b-4a3c-2d1e-0f1a-2b3c4d5e6f7a",
            "sources": [
              {
                "uri": "https://example.com/assets/product-red-video.mp4",
                "key": "product-red-video"
              }
            ],
            "name": {
              "en-US": "Red Variant Video",
              "de-DE": "Rote Variante Video"
            },
            "description": {
              "en-US": "Product demonstration video for red variant",
              "de-DE": "Produktdemonstrationsvideo für rote Variante"
            },
            "tags": ["video", "red", "large"]
          }
        ]
      }
    }
  ]
}

Check if Variant exists

Check if Variant exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/variants/{id}
Checks if a Variant exists by its ID. Returns a 200 status if the Variant exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the Variant.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/variants/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Variant exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/variants/key={key}
Checks if a Variant exists by its key. Returns a 200 status if the Variant exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the Variant.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/variants/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Variant exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/variants
Checks if a Variant exists for the provided query predicate. Returns a 200 status if any Variants match, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
QueryPredicate
​
Query Predicates on Attributes are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/variants?where={where} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Create Variant

POST
https://api.{region}.commercetools.com/{projectKey}/variants
Creates a new Variant with only the current representation. Produces the VariantCreated Message.
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:VariantDraftasapplication/json
Response:
201

Variant

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/variants -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "product" : {
    "typeId" : "product",
    "id" : "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "publish" : false,
  "sku" : "SKU-BLUE-M-001",
  "key" : "blue-medium-variant",
  "images" : [ {
    "url" : "https://example.com/images/variant-blue-medium.jpg",
    "label" : "Blue Medium Variant",
    "dimensions" : {
      "w" : 800,
      "h" : 600
    }
  } ],
  "attributes" : [ {
    "name" : "color",
    "value" : "blue"
  }, {
    "name" : "size",
    "value" : "M"
  } ],
  "assets" : [ {
    "sources" : [ {
      "uri" : "https://example.com/assets/variant-demo-video.mp4",
      "key" : "demo-video"
    } ],
    "name" : {
      "en-US" : "Variant Demo Video",
      "de-DE" : "Variant-Demonstrationsvideo"
    },
    "description" : {
      "en-US" : "Detailed demonstration of the variant features",
      "de-DE" : "Detaillierte Demonstration der Variant-Merkmale"
    },
    "tags" : [ "video", "demo", "tutorial" ]
  } ]
}
DATA
201 Response Example: Variantjson
{
  "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
  "version": 1,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModifiedAt": "2024-01-16T14:20:00.000Z",
  "lastModifiedBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "key": "variant-blue-medium",
  "variantId": 1,
  "product": {
    "typeId": "product",
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "published": false,
  "current": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/variant-blue-medium.jpg",
        "label": "Blue Medium Variant",
        "dimensions": {
          "w": 800,
          "h": 600
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/variant-demo-video.mp4",
            "key": "demo-video"
          }
        ],
        "name": {
          "en-US": "Variant Demo Video",
          "de-DE": "Variant-Demonstrationsvideo"
        },
        "description": {
          "en-US": "Detailed demonstration of the variant features",
          "de-DE": "Detaillierte Demonstration der Variant-Merkmale"
        },
        "tags": ["video", "demo", "tutorial"]
      }
    ]
  }
}

Update Variant

Update Variant by ID

POST
https://api.{region}.commercetools.com/{projectKey}/variants/{id}

Updates a Variant identified by its ID.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the Variant.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the Variant on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​
Array of VariantUpdateAction​

Update actions to be performed on the Variant.

Response:
200

Variant

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/variants/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "setSku",
    "sku" : "SKU-BLUE-M-002",
    "staged" : true
  } ]
}
DATA
200 Response Example: Variantjson
{
  "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
  "version": 2,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModifiedAt": "2024-01-17T09:15:00.000Z",
  "lastModifiedBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "key": "variant-blue-medium",
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "published": false,
  "current": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/variant-blue-medium.jpg",
        "label": "Blue Medium Variant",
        "dimensions": {
          "w": 800,
          "h": 600
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/variant-demo-video.mp4",
            "key": "demo-video"
          }
        ],
        "name": {
          "en-US": "Variant Demo Video",
          "de-DE": "Variant-Demonstrationsvideo"
        },
        "description": {
          "en-US": "Detailed demonstration of the variant features",
          "de-DE": "Detaillierte Demonstration der Variant-Merkmale"
        },
        "tags": ["video", "demo", "tutorial"]
      }
    ]
  },
  "staged": {
    "sku": "SKU-BLUE-M-002"
  }
}

Update Variant by Key

POST
https://api.{region}.commercetools.com/{projectKey}/variants/key={key}

Updates a Variant identified by its key.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the Variant.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the Variant on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​
Array of VariantUpdateAction​

Update actions to be performed on the Variant.

Response:
200

Variant

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/variants/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "setSku",
    "sku" : "SKU-BLUE-M-002",
    "staged" : true
  } ]
}
DATA
200 Response Example: Variantjson
{
  "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
  "version": 2,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModifiedAt": "2024-01-17T09:15:00.000Z",
  "lastModifiedBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "key": "variant-blue-medium",
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "published": false,
  "current": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/variant-blue-medium.jpg",
        "label": "Blue Medium Variant",
        "dimensions": {
          "w": 800,
          "h": 600
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/variant-demo-video.mp4",
            "key": "demo-video"
          }
        ],
        "name": {
          "en-US": "Variant Demo Video",
          "de-DE": "Variant-Demonstrationsvideo"
        },
        "description": {
          "en-US": "Detailed demonstration of the variant features",
          "de-DE": "Detaillierte Demonstration der Variant-Merkmale"
        },
        "tags": ["video", "demo", "tutorial"]
      }
    ]
  },
  "staged": {
    "sku": "SKU-BLUE-M-002"
  }
}

Bulk update Variants

POST
https://api.{region}.commercetools.com/{projectKey}/variants/bulk
Applies update actions to multiple Variants in a single request. Returns a 207 Multi-Status response with the result for each Variant. Each Variant is updated independently, so some may succeed while others fail.
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
versionControl
​
String
​

Controls whether optimistic concurrency is enforced for each item.

  • On (default): each item must include a version field. A ConcurrentModification error is returned for any item whose version does not match.
  • Off: version fields are ignored and updates are applied without version checks.
Default: On​
Request Body:VariantBulkUpdateasapplication/json
Response:
207

VariantBulkUpdateResponse

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/variants/bulk -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "items" : [ {
    "id" : "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
    "version" : 1
  }, {
    "key" : "my-variant-key",
    "version" : 3
  } ],
  "actions" : [ {
    "action" : "publish"
  } ]
}
DATA
207 Response Example: VariantBulkUpdateResponsejson
{
  "successCount": 1,
  "failureCount": 1,
  "results": [
    {
      "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
      "status": "Success",
      "resource": {
        "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
        "version": 2
      }
    },
    {
      "id": "2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
      "status": "Fail",
      "errors": [
        {
          "code": "ConcurrentModification",
          "message": "Object 2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f has a different version than expected. Expected: 0 - Actual: 3.",
          "currentVersion": 3
        }
      ]
    }
  ]
}

Update actions

on Variant

Set SKU

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

Value to set. Must be unique.

staged​
Boolean​
If true, only the staged sku is updated. If false, both the current and staged sku are updated.
Default: true​
Example: json
{
  "action": "setSku",
  "sku": "SKU-12345",
  "staged": true
}

Set Key

Sets the key of the Variant. Generates the VariantKeySet Message.
action​
String​
"setKey"
key​
String​

Value to set. Must be unique.

Example: json
{
  "action": "setKey",
  "key": "my-variant-key"
}

Set Images

Sets the images of the Variant. Existing images will be replaced with the new ones. Generates the VariantImagesSet Message.
action​
String​
"setImages"
images​
Array of Image​

Images to set for the Variant.

staged​
Boolean​
If true, only the staged images are updated. If false, both the current and staged images are updated.
Default: true​
Example: json
{
  "action": "setImages",
  "images": [
    {
      "url": "https://example.com/product-image.jpg",
      "dimensions": {
        "w": 1024,
        "h": 76
      },
      "label": "Main product image"
    }
  ],
  "staged": true
}

Add External Image

Adds an image to existing variant's images. Generates the VariantImageAdded Message.
action​
String​
"addExternalImage"
image​
Image​
Value to add to images.
staged​
Boolean​
If true, only the staged images is updated. If false, both the current and staged images is updated.
Default: true​
Example: json
{
  "action": "addExternalImage",
  "image": {
    "url": "//myimage.jpg",
    "dimensions": {
      "w": 1400,
      "h": 1400
    },
    "label": "myImage"
  }
}

Remove Image

Removes a Variant's image.

action​
String​
"removeImage"
imageUrl​
String​

The URL of the image to remove.

staged​
Boolean​
If true, only the staged image is removed. If false, both the current and staged image is removed.
Default: true​
Example: json
{
  "action": "removeImage",
  "imageUrl": "//myimage2.jpg"
}

Set Assets

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

action​
String​
"setAssets"
assets​
Array of AssetDraft​

Assets to set for the Variant.

staged​
Boolean​
If true, only the staged assets are set. If false, both the current and staged assets are updated.
Default: true​
Example: json
{
  "action": "setAssets",
  "assets": [
    {
      "sources": [
        {
          "uri": "https://example.com/asset.jpg",
          "key": "main-image"
        }
      ],
      "name": {
        "en-US": "Product Image",
        "de-DE": "Produktbild",
        "fr-FR": "Image du produit",
        "es-ES": "Imagen del producto"
      },
      "description": {
        "en-US": "Main product image",
        "de-DE": "Hauptproduktbild",
        "fr-FR": "Image principale du produit",
        "es-ES": "Imagen principal del producto"
      },
      "tags": [
        "product",
        "main"
      ],
      "key": "main-product-asset"
    }
  ],
  "staged": true
}

Add Asset

Adds an asset to existing variant's assets.

action​
String​
"addAsset"
staged​
Boolean​
If true, only the staged assets are updated. If false, both the current and staged assets are updated.
Default: true​
asset​
AssetDraft​

Value to append.

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.
Example: json
{
  "action": "addAsset",
  "asset": {
    "sources": [
      {
        "uri": "//asset.mp4"
      }
    ],
    "name": {
      "de": "FirstAssetDE",
      "en": "FirstassetEN"
    }
  }
}

Remove Asset

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

Set Attributes

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

action​
String​
"setAttributes"
attributes​
Array of Attribute​
Attributes to set for the Variant according to the respective AttributeDefinition.
staged​
Boolean​
If true, only the staged attributes are updated. If false, both the current and staged attributes are updated.
Default: true​
Example: json
{
  "action": "setAttributes",
  "attributes": [
    {
      "name": "color",
      "value": "blue"
    },
    {
      "name": "size",
      "value": "M"
    }
  ],
  "staged": true
}

Set Attribute

Set a specific Variant attribute.

action​
String​
"setAttribute"
name​
String​

Name of the Attribute to set.

value​
Any​

Value to set for the Attribute. If empty, any existing value will be removed.

The AttributeType determines the format of the Attribute value to be provided:
staged​
Boolean​
If true, only the staged Attribute is set. If false, both the current and staged Attributes are set.
Default: true​
Example: json
{
  "action": "setAttribute",
  "name": "ExampleStringTypeAttribute",
  "value": "TextString"
}

Remove Staged Changes

Removes all staged changes from the Variant, only the current data remains. Generates the VariantStagedChangesRemoved Message.
action​
String​
"removeStagedChanges"
Example: json
{
  "action": "removeStagedChanges"
}

Publish

Publishes the Variant by copying the staged data to the current data and setting the published flag to true. Staged will be empty. The parent Product must be published before a Variant can be published. Generates the VariantPublished Message.
action​
String​
"publish"
Example: json
{
  "action": "publish"
}

Unpublish

Unpublishes the Variant by setting the published flag to false. Generates the VariantUnpublished Message.
action​
String​
"unpublish"
Example: json
{
  "action": "unpublish"
}

on Asset

Set Asset Key

Sets the key of an existing Asset on a Variant.

action​
String​
"setAssetKey"
staged​
Boolean​
If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
assetId​
String​
The id of the Asset to update.
assetKey​
String​

Value to set. If empty, any existing value will be removed.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action": "setAssetKey",
  "assetId": "{{assetId}}",
  "assetKey": "my-asset-key"
}

Change Asset Order

Changes the order of Assets on a Variant.

action​
String​
"changeAssetOrder"
staged​
Boolean​
If true, 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.
Example: json
{
  "action": "changeAssetOrder",
  "assetOrder": [
    "{{assetId1}}",
    "{{assetId2}}"
  ]
}

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.
action​
String​
"changeAssetName"
staged​
Boolean​
If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
assetId​
String​
The id of the Asset to update.
assetKey​
String​
The key of the Asset to update.
name​
LocalizedString​

New value to set. Must not be empty.

Example: json
{
  "action": "changeAssetName",
  "assetId": "{{assetId}}",
  "name": {
    "de": "Mein Asset",
    "en": "My asset"
  }
}

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.
action​
String​
"setAssetDescription"
staged​
Boolean​
If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
assetId​
String​
The id of the Asset to update.
assetKey​
String​
The key of the Asset to update.
description​
LocalizedString​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setAssetDescription",
  "assetId": "{{assetId}}",
  "description": {
    "de": "Dies ist eine Asset-Beschreibung",
    "en": "This is an asset description"
  }
}

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.
action​
String​
"setAssetTags"
staged​
Boolean​
If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
assetId​
String​
The id of the Asset to update.
assetKey​
String​
The key of the Asset to update.
tags​
Array of String​

Keywords for categorizing and organizing Assets.

Example: json
{
  "action": "setAssetTags",
  "assetId": "{{assetId}}",
  "tags": [
    "commercetools",
    "awesome"
  ]
}

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.
action​
String​
"setAssetSources"
staged​
Boolean​
If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
assetId​
String​
The id of the Asset to update.
assetKey​
String​
The key of the Asset to update.
sources​
Array of AssetSource​

Value to set.

MinItems: 1​
Example: json
{
  "action": "setAssetSources",
  "assetId": "{{assetId}}",
  "sources": [
    {
      "uri": "https://www.example.com/logo.svg",
      "key": "vector"
    }
  ]
}

Set Asset Custom Type

Sets or removes the Custom Type on an existing Asset of a Variant. The Asset to update must be specified using either assetId or assetKey.
action​
String​
"setAssetCustomType"
staged​
Boolean​
If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
assetId​
String​
The id of the Asset to update.
assetKey​
String​
The key of the Asset to update.
type​
TypeResourceIdentifier​
Defines the Type that extends the Asset with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Asset.
fields​
FieldContainer​
Sets the Custom Fields fields for the Asset.
Example: json
{
  "action": "setAssetCustomType",
  "assetId": "{{assetId}}",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

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.
action​
String​
"setAssetCustomField"
staged​
Boolean​
If true, only the staged Asset is updated. If false, both the current and staged Asset is updated.
Default: true​
assetId​
String​
The id of the Asset to update.
assetKey​
String​
The key of the Asset to update.
name​
String​
Name of the Custom Field.
value​
CustomFieldValue​
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.
Example: json
{
  "action": "setAssetCustomField",
  "assetId": "{{assetId}}",
  "name": "exampleStringField",
  "value": "TextString"
}

Delete Variant

If the deleted Variant was the defaultVariant of its Product, the reference is automatically cleared and the response includes a DefaultVariantDeleted warning.

Delete Variant by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/variants/{id}

Deletes a Variant identified by its ID.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the Variant.
Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Variant

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/variants/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Variantjson
{
  "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
  "version": 2,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModifiedAt": "2024-01-16T14:20:00.000Z",
  "lastModifiedBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "key": "variant-blue-medium",
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "published": false,
  "current": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/variant-blue-medium.jpg",
        "label": "Blue Medium Variant",
        "dimensions": {
          "w": 800,
          "h": 600
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/variant-demo-video.mp4",
            "key": "demo-video"
          }
        ],
        "name": {
          "en-US": "Variant Demo Video",
          "de-DE": "Variant-Demonstrationsvideo"
        },
        "description": {
          "en-US": "Detailed demonstration of the variant features",
          "de-DE": "Detaillierte Demonstration der Variant-Merkmale"
        },
        "tags": ["video", "demo", "tutorial"]
      }
    ]
  },
  "staged": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/product-blue-medium-updated.jpg",
        "label": "Blue Medium Variant - Updated",
        "dimensions": {
          "w": 1200,
          "h": 900
        }
      },
      {
        "url": "https://example.com/images/product-blue-medium-detail.jpg",
        "label": "Blue Medium Variant - Detail",
        "dimensions": {
          "w": 1200,
          "h": 900
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      },
      {
        "name": "material",
        "value": "cotton"
      },
      {
        "name": "weight",
        "value": 250
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/product-video-v2.mp4",
            "key": "product-video-v2"
          }
        ],
        "name": {
          "en-US": "Product Video - Updated",
          "de-DE": "Produktvideo - Aktualisiert",
          "fr-FR": "Vidéo du produit - Mise à jour",
          "es-ES": "Video del producto - Actualizado"
        },
        "description": {
          "en-US": "Updated product demonstration video with new features",
          "de-DE": "Aktualisiertes Produktdemonstrationsvideo mit neuen Funktionen",
          "fr-FR": "Vidéo de démonstration mise à jour avec de nouvelles fonctionnalités",
          "es-ES": "Video de demostración actualizado con nuevas características"
        },
        "tags": ["video", "demo", "updated"]
      }
    ]
  }
}

Delete Variant by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/variants/key={key}

Deletes a Variant identified by its key.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the Variant.
Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Variant

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/variants/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Variantjson
{
  "id": "7a3b5c8d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
  "version": 2,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModifiedAt": "2024-01-16T14:20:00.000Z",
  "lastModifiedBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "abc123xyz789",
    "isPlatformClient": false
  },
  "key": "variant-blue-medium",
  "variantId": 2,
  "product": {
    "typeId": "product",
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "published": false,
  "current": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/variant-blue-medium.jpg",
        "label": "Blue Medium Variant",
        "dimensions": {
          "w": 800,
          "h": 600
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/variant-demo-video.mp4",
            "key": "demo-video"
          }
        ],
        "name": {
          "en-US": "Variant Demo Video",
          "de-DE": "Variant-Demonstrationsvideo"
        },
        "description": {
          "en-US": "Detailed demonstration of the variant features",
          "de-DE": "Detaillierte Demonstration der Variant-Merkmale"
        },
        "tags": ["video", "demo", "tutorial"]
      }
    ]
  },
  "staged": {
    "sku": "SKU-BLUE-M-001",
    "images": [
      {
        "url": "https://example.com/images/product-blue-medium-updated.jpg",
        "label": "Blue Medium Variant - Updated",
        "dimensions": {
          "w": 1200,
          "h": 900
        }
      },
      {
        "url": "https://example.com/images/product-blue-medium-detail.jpg",
        "label": "Blue Medium Variant - Detail",
        "dimensions": {
          "w": 1200,
          "h": 900
        }
      }
    ],
    "attributes": [
      {
        "name": "color",
        "value": "blue"
      },
      {
        "name": "size",
        "value": "M"
      },
      {
        "name": "material",
        "value": "cotton"
      },
      {
        "name": "weight",
        "value": 250
      }
    ],
    "assets": [
      {
        "id": "9f8e7d6c-5b4a-3c2d-1e0f-1a2b3c4d5e6f",
        "sources": [
          {
            "uri": "https://example.com/assets/product-video-v2.mp4",
            "key": "product-video-v2"
          }
        ],
        "name": {
          "en-US": "Product Video - Updated",
          "de-DE": "Produktvideo - Aktualisiert",
          "fr-FR": "Vidéo du produit - Mise à jour",
          "es-ES": "Video del producto - Actualizado"
        },
        "description": {
          "en-US": "Updated product demonstration video with new features",
          "de-DE": "Aktualisiertes Produktdemonstrationsvideo mit neuen Funktionen",
          "fr-FR": "Vidéo de démonstration mise à jour avec de nouvelles fonctionnalités",
          "es-ES": "Video de demostración actualizado con nuevas características"
        },
        "tags": ["video", "demo", "updated"]
      }
    ]
  }
}