# Variants 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](/api/projects/products.md). 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 **10000** [Variants](/api/projects/variants.md#variant) per [Product](/api/projects/products.md#product) can be created. - This endpoint is only available for Projects with [productCatalogModel](/api/projects/project.md#productcatalogmodel) set to `Modular`. - In the `Modular` catalog model, pricing is exclusively handled through [Standalone Prices](/api/projects/standalone-prices.md). [Embedded Prices](/api/pricing-and-discounts-overview.md#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](/api/projects/variant-projections.md) instead. ## Representations #### Variant [type definition](/api/projects/variants.md?urn=ctp:api:type:Variant). #### VariantDraft [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantDraft). #### VariantPagedQueryResponse [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantPagedQueryResponse). #### VariantData [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantData). #### VariantBulkUpdate [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantBulkUpdate). #### VariantBulkUpdateItem [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantBulkUpdateItem). #### VariantBulkUpdateResponse [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantBulkUpdateResponse). #### VariantBulkUpdateResult [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantBulkUpdateResult). #### VariantBulkUpdateSuccessResult [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantBulkUpdateSuccessResult). #### VariantBulkUpdateResource [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantBulkUpdateResource). #### VariantBulkUpdateFailResult [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantBulkUpdateFailResult). ## Get Variant ### Get Variant by ID [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/\{id}:GET). ### Get Variant by Key [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/key=\{key}:GET). ## Query Variants When querying an [Attribute](/api/projects/products.md#attribute), we recommend that you use the performance-optimized [Variant Projections API](/api/projects/variant-projections.md) whenever possible. For more information, see [inefficient patterns](/api/predicates/query.md#inefficient-patterns). [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants:GET). ## Check if Variant exists ### Check if Variant exists by ID [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/\{id}:HEAD). ### Check if Variant exists by Key [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/key=\{key}:HEAD). ### Check if Variant exists by Query Predicate [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants:HEAD). ## Create Variant [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants:POST). ## Update Variant ### Update Variant by ID [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/\{id}:POST). ### Update Variant by Key [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/key=\{key}:POST). ## Bulk update Variants [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/bulk:POST). ## Update actions #### on Variant ##### Set SKU [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetSkuAction). ##### Set Key [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetKeyAction). ##### Set Images [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetImagesAction). ##### Add External Image [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantAddExternalImageAction). ##### Remove Image [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantRemoveImageAction). ##### Set Assets [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAssetsAction). ##### Add Asset [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantAddAssetAction). ##### Remove Asset [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantRemoveAssetAction). ##### Set Attributes [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAttributesAction). ##### Set Attribute [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAttributeAction). ##### Remove Staged Changes [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantRemoveStagedChangesAction). ##### Publish [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantPublishAction). ##### Unpublish [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantUnpublishAction). #### on Asset ##### Set Asset Key [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAssetKeyAction). ##### Change Asset Order [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantChangeAssetOrderAction). ##### Change Asset Name [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantChangeAssetNameAction). ##### Set Asset Description [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAssetDescriptionAction). ##### Set Asset Tags [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAssetTagsAction). ##### Set Asset Sources [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAssetSourcesAction). ##### Set Asset Custom Type [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAssetCustomTypeAction). ##### Set Asset Custom Field [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetAssetCustomFieldAction). #### on Image ##### Move Image To Position [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantMoveImageToPositionAction). ##### Set Image Label [type definition](/api/projects/variants.md?urn=ctp:api:type:VariantSetImageLabelAction). ## Upload Variant image Uploads a binary image file to a given [Variant](/urn?urn=ctp%3Aapi%3Atype%3AVariant), identified by its `id`. After upload, the system converts the original image to several [sizes](/api/projects/products.md#image) that are available on the builtin Content Delivery Network (CDN). Supported image formats are JPEG, PNG, and GIF. The maximum file size of the image to upload is **10 MB**. Only images in **sRGB** color space are supported. When uploading images with other color spaces, like [Adobe RGB](https://www.adobe.com/digitalimag/adobergb.html), the API returns a [400 Bad Request Error](/api/errors.md#400-bad-request-1) with code `InvalidInput` and the message `Unsupported image data. Not able to identify the color model of your image.` In such case, you must fix the issue and upload the image again. If any other error response is returned, upload the image again. The [image](/api/projects/products.md#image) uploaded to the CDN is publicly available and its `url` might be shared across different resources (such as Variants and Products) in either the same Project or in other Projects. If you remove the image from a Variant or delete the Variant, the image is not deleted from the CDN and remains available at its original URL. Depending on the size of the original image, the API returns different status codes that indicate the status of the image upload at the time the API responds. If the original image is small, the API responds with `200 OK`, and if the image is larger, it responds with `202 Accepted`. - A `200 OK` response is returned when all [sizes](/api/projects/products.md#image) of the image have been successfully uploaded to the CDN. - A `202 Accepted` response is returned when the `small` size of the image has been successfully uploaded to the CDN, but the upload of the other sizes is still ongoing. These other sizes will be available soon thereafter. [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/\{id}/images:POST). The cURL example below adds an [Image](/api/projects/products.md#image) to the staged data of the Variant specified in path parameter `{id}`: ```bash curl -X POST -H "Content-Type: image/jpeg" -H "Authorization: Bearer {token}" --upload-file "detail.jpg" "https://api.{region}.commercetools.com/{projectKey}/variants/{id}/images?filename=detail.jpg" ``` As the `filename` parameter was included (`filename=detail.jpg`), an example URL of the uploaded image is `https://{commercetools-cdn}/detail-6xAq4Efp.jpg`. File upload using [Content-Type: multipart/form-data](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2) is currently not supported. Learn more about images in our self-paced Images and Assets module. ## Delete Variant If the deleted Variant was the [defaultVariant](/api/projects/products.md#product) of its Product, the reference is automatically cleared and the response includes a `DefaultVariantDeleted` warning. ### Delete Variant by ID [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/\{id}:DELETE). ### Delete Variant by Key [endpoint definition](/api/projects/variants.md?urn=ctp:api:endpoint:/\{projectKey}/variants/key=\{key}:DELETE). ## Related pages - [Area overview page with navigation](/api.md) - [Next page: Variant Attributes](/api/projects/variant-attributes.md)