This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Importing Product Variants

Create and update ProductVariants in your Project.

The Product Variant data to import is represented by ProductVariantImport and included in a ProductVariantImportRequest, which is imported using Import ProductVariants.

This endpoint does not support importing Embedded Price data for Product Variants. To import Embedded Price data to a Product Variant, use the Importing Embedded Prices endpoint.

If you are only importing Attribute data, use the Importing Product Variant Patches endpoint.

For more information, see Which Product import endpoint should be used?

Read the Nested Attribute tutorial to learn how to create/update nested Attribute values with the commercetools Import API.

When importing Product Variant data to update an existing Product Variant, you must include existing values for fields or they will be removed when the Product Variant is imported.

Representations

ProductVariantImportRequest

The request body to import ProductVariants. Contains data for ProductVariants to be created or updated in a Project.

type
String
"product-variant"

The Product Variant import resource type.

resources

The product variant import resources of this request.

MaxItems: 20
Example: json
{
"type": "product-variant",
"resources": [
{
"key": "red-t-shirt",
"sku": "red-t-shirt",
"product": {
"key": "t-shirt",
"typeId": "product"
},
"isMasterVariant": true,
"attributes": [
{
"name": "new",
"type": "boolean",
"value": true
},
{
"name": "weight",
"type": "number",
"value": 12.5
}
],
"assets": [
{
"id": "uuid-kafar7545792sd6r",
"key": "uuid-kafar7545792sd6r",
"sources": [
{
"uri": "http://www.example.com"
}
],
"name": {
"en": "asset name"
}
}
],
"images": [
{
"url": "https://www.commercetools.com/cli/data/253234387_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
},
"label": "tank top image Font"
}
]
}
]
}

ProductVariantImport

The data representation for a ProductVariant to be imported that is persisted as a ProductVariant in the Project.

key
String

User-defined unique identifier. If a ProductVariant with this key exists on the specified product, it will be updated with the imported data.

sku
String

Maps to ProductVariant.sku.

isMasterVariant
Boolean

Maps to ProductVariant.isMasterVariant.

attributes
Array of Attribute

Maps to ProductVariant.attributes. The referenced attribute must be defined in an already existing ProductType in the project, or the state of the ImportOperation will be unresolved.

images
Array of Image

Maps to ProductVariant.images.

assets
Array of Asset

Maps to ProductVariant.assets.

publish
Boolean

If publish is set to either true or false, both staged and current projections are set to the same value provided by the import data. If publish is not set, the staged projection is set to the provided import data, but the current projection stays unchanged. However, if the import data contains no update, that is, if it matches the staged projection of the existing Product, the import induces no change in the existing Product whether publish is set or not.

product

The Product to which this Product Variant belongs. Maps to ProductVariant.product. The Reference to the Product with which the ProductVariant is associated. If referenced Product does not exist, the state of the ImportOperation will be set to unresolved until the necessary Product is created.

Attribute

Represents the value of attributes of a ProductVariant.

  • name - String - Optional
    Required if used for ProductVariant import. Must not be set when used for ProductVariantPatch import. Must match name of an AttributeDefinition of the ProductType.
  • type - String - Optional
    Must match type of an AttributeDefinition of the ProductType. Must be one of "boolean", "boolean-set", "date", "date-set", "datetime", "datetime-set", "enum", "enum-set", "lenum", "lenum-set", "ltext", "ltext-set", "money", "money-set", "number", "number-set", "reference", "reference-set", "text", "text-set", "time", or "time-set".
    Do not include this field when importing nested Attributes.
  • value - Required
    Depends on type. See List of Attributes. When importing nested Attributes, value should be an array of Attributes. For an example, see the Handling Structured and Nested Product Data tutorial.

Image

An Image uploaded to commercetools Composable Commerce is stored in a Content Delivery Network and it's available in several pre-defined sizes. If you already have an image stored on an external service, you can save the URL when creating a new product or adding a variant, or you can add it later.

url
String

URL of the image in its original size. The URL must be unique within a single variant. It can be used to obtain the image in different sizes.

dimensions

Dimensions of the original image. This can be used by your application, for example, to determine whether the image is large enough to display a zoom view.

label
String

Custom label that can be used, for example, as an image description.

Asset

key
String

User-defined identifier for the asset. Asset keys are unique inside their container (a product variant or a category).

sources
Array of AssetSource
MinItems: 1
name
description
tags
Array of String
custom

The representation to be sent to the server when creating a resource with custom fields.

AssetSource

An AssetSource is a representation of an Asset in a specific format, for example, a video in a certain encoding or an image in a certain resolution.

key
String
uri
String
dimensions

The width and height of the Asset Source.

contentType
String

AssetDimensions

The width and height of the Asset Source.

w
Int

The width of the asset source.

h
Int

The height of the asset source.

List of Attributes

The possible types for Attribute are listed below.

BooleanAttribute

This type represents an attribute whose value is either "true" or "false".

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"boolean"
value
Boolean

BooleanSetAttribute

This type represents an attribute whose value is set of boolean values.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"boolean-set"
value
Array of Boolean

DateAttribute

This type represents an attribute whose value is a date.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"date"
value
Date

DateSetAttribute

This type represents an attribute whose value is a set of dates.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"date-set"
value
Array of Date-only

DateTimeAttribute

This type represents an attribute whose value is a date with time.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"datetime"
value

DateTimeSetAttribute

This type represents an attribute whose value is a set of dates with time.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"datetime-set"
value
Array of Datetime

EnumAttribute

This type represents an attribute whose value is an enum. The attribute value refers to the key of the enum value.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"enum"
value
String

EnumSetAttribute

This type represents an attribute whose value is an enum. The attribute value refers to the key of the enum value.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"enum-set"
value
Array of String

LocalizableEnumAttribute

This type represents an attribute whose value is a localized enum. The attribute value refers to the key of the enum value.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"lenum"
value
String

LocalizableEnumSetAttribute

This type represents an attribute whose value is a localized enum. The attribute value refers to the key of the enum value.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"lenum-set"
value
Array of String

LocalizableTextAttribute

This type represents an attribute whose value is a localized text.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"ltext"
value

LocalizableTextSetAttribute

This type represents an attribute whose value is a localized text.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"ltext-set"
value
Array of LocalizedString

MoneyAttribute

This type represents an attribute whose value is a money object.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"money"
value

MoneySetAttribute

This type represents an attribute whose value is a set of money objects.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"money-set"
value
Array of TypedMoney

NumberAttribute

This type represents an attribute whose value is a number.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"number"
value
Float

NumberSetAttribute

This type represents an attribute whose value is a set of numbers.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"number-set"
value
Array of Number

ReferenceAttribute

This type represents an attribute whose value is a key reference.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"reference"
value

References a resource by key.

Example: json
{
"type": "reference",
"name": "product-custom-object-ref-attribute",
"value": {
"key": "custom-object-key",
"container": "custom-object-container",
"typeId": "key-value-document"
}
}

ReferenceSetAttribute

This type represents an attribute whose value is a set of references.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"reference-set"
value
Array of KeyReference

TextAttribute

This type represents an attribute whose value is a string.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"text"
value
String

TextSetAttribute

This type represents an attribute whose value is a set of strings.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"text-set"
value
Array of String

TimeAttribute

This type represents an attribute whose value is a time.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"time"
value
Time

TimeSetAttribute

This type represents an attribute whose value is a set of times.

name
String

The name of this attribute must match a name of the product types attribute definitions. The name is required if this type is used in a product variant and must not be set when used in a product variant patch.

type
String
"time-set"
value
Array of Time-only

Import ProductVariants

POST
https://import.{region}.commercetools.com/{projectKey}/product-variants/import-containers/{importContainerKey}

Creates a request for creating new ProductVariants or updating existing ones.

OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

The Region in which the Project is hosted.

projectKey
String

The Project key.

importContainerKey
String

The ImportContainer used to create the new resource

Request Body:ProductVariantImportRequestasapplication/json
Response:
201ImportResponseasapplication/json