Variants (Partial Update)

Description

Creates or updates a variant identified by the uuid or externalId in the request body. If the identifier matches an existing variant, it is updated. If not, a new variant is created (upsert behavior). Omitted fields are left unchanged on update, or set to their defaults on creation.

Updates a variant of a product

Product support

product can only be provided on new variants. If your variant already exists, this field will be ignored. This field was called productId in previous versions and would only accept an identifier. The new field is now named product and will accept a full product resource on creation.

Attributes

Attributes referenced by name that do not yet exist are automatically created. You do not need to create attribute definitions before assigning them to a variant.

Important note about images

Images can feature a sort order to appear in different order in the client applications. Our current client applications expect the primary image to be at sortOrder: 0 to be shown as the primary image. Not using position 0 will show a placeholder image instead of the first one available.

See the Aerial Spec for more details.

File Naming Convention

TGEN_variants_partialupdate_2026-08_<optionalSuffix>.csv

importType: partialupdate
apiVersion: 2026-08

Columns

Nested object fields are flattened into columns using dot notation (parent.child). Array fields are flattened using zero-based index notation, one element per column (field[0], field[1], and so on).

Note: A whole array cannot be passed in a single column: a literal value such as ['value-1','value-2'] will be rejected. To import multiple array elements, add one indexed column per element. Rows in the table below with type array describe the field as a whole and are not valid CSV column headers.

Column Header	Description	Key Information	Type	Required
`uuid`	UUID of the resource that can be expressed using a value as defined in its types.		`string`	No
`externalId`	External ID of the resource that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`product`	UUID, External ID or object representation of a UUID or external ID of a product to assign this variant to. (Creation only)		`string`	No
`product.uuid`	UUID of the resource		`string`	No
`product.externalId`	External ID of the resource		`string`	No
`upc`	UPC of the variant that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`status`	Status of the variant that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.	Allowed: available, discontinued, unavailable	`string`	No
`isFinalSale`	Declares this variant is not eligible for returns that can be expressed using a value as defined in its types.		`boolean`	No
`isOpenPricePoint`	States if the price can be customized that can be expressed using a value as defined in its types.		`boolean`	No
`minOpenPricePoint`	The minimum open price point for this variant. that can be expressed using a value as defined in its types.		`number`	No
`maxOpenPricePoint`	The maximum open price point for this variant. that can be expressed using a value as defined in its types.		`number`	No
`isSerialized`	Is the variant controlled by serial numbers. that can be expressed using a value as defined in its types.		`boolean`	No
`availableDate`	Date from which the variant is available. When null, the variant is always considered available. that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`discontinuedDate`	Date after which the variant is discontinued. When null, the variant is never considered discontinued. that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`images`	A collection of Images of the product that can be expressed using “SET_AS_NULL” (to reset all existing values) or a value as defined in its types.	Not a CSV column header. Pass each array element in its own indexed column (`images[0]`, `images[1]`, and so on).	`array`	No
`images[0]`	Array element		`mixed`	No
`images[0].sourceUrl`	The original url of the image. that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	Yes
`images[0].sortOrder`	The ascending sort order value to order images for the same product/variant. To set an image as the primary image, please use sortOrder 0. that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`integer`	No
`localizedData`	A collection of Localizations of the variant that can be expressed using “SET_AS_NULL” (to reset all existing values) or a value as defined in its types.	Not a CSV column header. Pass each array element in its own indexed column (`localizedData[0]`, `localizedData[1]`, and so on).	`array`	No
`localizedData[0]`	Array element		`mixed`	No
`localizedData[0].languageCode`	Language code of localization that can be expressed using a value as defined in its types.		`string`	Yes
`localizedData[0].name`	Localized variant name that can be expressed using a value as defined in its types.		`string`	No
`localizedData[0].description`	Localized variant description that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`localizedData[0].url`	URL to a localized web page giving more details about the variant that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`attributes`	A collection of attribute that can be expressed using “SET_AS_NULL” (to reset all existing values) or a value as defined in its types.	Not a CSV column header. Pass each array element in its own indexed column (`attributes[0]`, `attributes[1]`, and so on).	`array`	No
`attributes[0]`	Array element		`mixed`	No
`attributes[0].name`	Name of the attribute		`string`	Yes
`attributes[0].languageExternalId`	Language code of the attribute that can be expressed using a value as defined in its types.		`string`	Yes
`attributes[0].value`	Value of the attribute, this will be any type casted to string but supports all basic types that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`optionValues`	A collection of option_values that can be expressed using “SET_AS_NULL” (to reset all existing values), uuids or expanded objects of the accepted type.	Not a CSV column header. Pass each array element in its own indexed column (`optionValues[0]`, `optionValues[1]`, and so on).	`array`	No
`optionValues[0]`	Array element		`mixed`	No
`optionValues[0].uuid`	UUID of the resource that can be expressed using a value as defined in its types.		`string`	No
`optionValues[0].externalId`	External ID of the resource that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`optionValues[0].type`	UUID, External ID or object representation of a option type		`string`	No
`optionValues[0].type.uuid`	UUID of the resource		`string`	No
`optionValues[0].type.externalId`	External ID of the resource		`string`	No
`optionValues[0].sortOrder`	Sort order of the value against other values of this type that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`integer`	No
`optionValues[0].value`	The value used to render the option, it can be a string or a code that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`optionValues[0].localizedData`	A collection of Localizations of the option value that can be expressed using “SET_AS_NULL” (to reset all existing values) or a value as defined in its types.	Not a CSV column header. Pass each array element in its own indexed column (`optionValues[0].localizedData[0]`, `optionValues[0].localizedData[1]`, and so on).	`array`	No
`optionValues[0].localizedData[0]`	Array element		`mixed`	No
`optionValues[0].localizedData[0].languageCode`	Language code of localization that can be expressed using a value as defined in its types.		`string`	Yes
`optionValues[0].localizedData[0].name`	Localized option value name that can be expressed using a value as defined in its types.		`string`	No
`optionValues[0].localizedData[0].presentation`	Localized option value presentation string that can be expressed using a value as defined in its types.		`string`	No
`optionValues[0].optionValueCategories`	A collection of optionValueCategories that can be expressed using “SET_AS_NULL” (to reset all existing values), uuids or expanded objects of the accepted type.	Not a CSV column header. Pass each array element in its own indexed column (`optionValues[0].optionValueCategories[0]`, `optionValues[0].optionValueCategories[1]`, and so on).	`array`	No
`optionValues[0].optionValueCategories[0]`	Array element		`mixed`	No
`optionValues[0].optionValueCategories[0].uuid`	UUID of the resource that can be expressed using a value as defined in its types.		`string`	No
`optionValues[0].optionValueCategories[0].externalId`	External ID of the resource that can be expressed using “SET_AS_NULL” (to reset the existing value) or a value as defined in its types.		`string`	No
`optionValues[0].optionValueCategories[0].localizedData`	A collection of Localizations of the option value category that can be expressed using “SET_AS_NULL” (to reset all existing values) or a value as defined in its types.	Not a CSV column header. Pass each array element in its own indexed column (`optionValues[0].optionValueCategories[0].localizedData[0]`, `optionValues[0].optionValueCategories[0].localizedData[1]`, and so on).	`array`	No
`optionValues[0].optionValueCategories[0].localizedData[0]`	Array element		`mixed`	No
`optionValues[0].optionValueCategories[0].localizedData[0].languageCode`	Language code of localization that can be expressed using a value as defined in its types.		`string`	Yes
`optionValues[0].optionValueCategories[0].localizedData[0].name`	Localized option value category name that can be expressed using a value as defined in its types.		`string`	No
`optionValues[0].optionValueCategories[0].parentCategory`	UUID or external ID of a parent option value category that can be expressed using “SET_AS_NULL” (to reset the existing value) or a structure of {“uuid”: “string”, “externalId”: “string”} (to provide a more expressive identifier) or a value as defined in its types.		`string`	No
`optionValues[0].optionValueCategories[0].parentCategory.uuid`	UUID of the resource		`string`	No
`optionValues[0].optionValueCategories[0].parentCategory.externalId`	External ID of the resource		`string`	No

Sample CSV

See the following variants CSV sample file.

variants Sample 1

Note: The sample CSV may contain sample ID fields which reference other resources that do not match the data in your environment. You may omit any non-required fields from the sample CSV, reference the table above for required fields.

Variants (Partial Update)

Description#