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 Choose the right Product import endpoint.

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

ProductVariantImportRequest

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

`type` ImportResourceType	`"product-variant"` The Product Variant import resource type.
`resources` Array of ProductVariantImport	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	When creating a new ProductVariant, set to `false`; otherwise, the import operation will fail with a NewMasterVariantAdditionNotAllowed error. Set to `true` if the ProductVariant exists and you want to set this ProductVariant as the Master Variant.
`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`.
`staged` Boolean	Set to `false` to update both the current and staged projections of the Product with the new Product Variant data. Leave empty or set to `true` to only update the staged projection. Default: `true`
`product` ProductKeyReference	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` AssetDimensions	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` LocalizedString
`description` LocalizedString
`tags` Array of String
`custom` 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` AssetDimensions	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.

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` DateTime

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` LocalizedString

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` TypedMoney

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` KeyReference	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

Importing Product Variants

Representations

ProductVariantImportRequest

ProductVariantImport

Attribute

Image

Asset

AssetSource

AssetDimensions

List of Attributes

BooleanAttribute

BooleanSetAttribute

DateAttribute

DateSetAttribute

DateTimeAttribute

DateTimeSetAttribute

EnumAttribute

EnumSetAttribute

LocalizableEnumAttribute

LocalizableEnumSetAttribute

LocalizableTextAttribute

LocalizableTextSetAttribute

MoneyAttribute

MoneySetAttribute

NumberAttribute

NumberSetAttribute

ReferenceAttribute

ReferenceSetAttribute

TextAttribute

TextSetAttribute

TimeAttribute

TimeSetAttribute

Import ProductVariants