Setting up multiple variants of an item

Overview

Variant groups allow sellers to display multiple versions of the same product on a single Walmart item page. Common examples include products that vary by color, size, flavor, pattern, count, or other supported attributes while sharing the same core product information.

Grouping related items into a variant group improves product discovery and allows customers to compare available options without navigating between multiple item pages.

Use the bulk item setup API with feedType=MP_ITEM to create variant groups and feedType=MP_MAINTENANCE to update existing variant groups. Each variant is submitted as an individual item and linked to other variants through a shared variant group ID and variant attribute values.

Use cases

• Create a single customer experience for products available in multiple colors, sizes, or configurations.
• Group related items together while maintaining separate SKUs and inventory.
• Add new variants to an existing variant group.
• Change the primary variant within an existing group.
• Update variant relationships through item maintenance feeds.

How variant groups work

Each item in a variant group must be created as a separate item.

For example, if a curtain set is available in 2 sizes and 6 colors, you must create 12 individual items, one for each size/color combination.

All items in a variant group must:

• Share the same variantGroupId
• Use the same variantAttributeNames
• Provide values for the same variant attributes across all items in the group
• Represent a unique combination of variant attribute values
• Contain exactly one primary variant within the group

An item can belong to only one variant group.

Variant group attributes

Variant groups are defined using a small set of variant-specific attributes included in the item setup feed. The following attributes are used to create and manage variant groups.

variantGroupId

Identifies all items that belong to the same variant group.

• Every item in the group must use the same value.
• Different variant groups must use different IDs.
• Sellers are responsible for ensuring uniqueness.
• The value should remain stable throughout the lifetime of the variant group.

Example:

"variantGroupId": "HANESV025"

isPrimaryVariant

Identifies the default item displayed to customers.

Each variant group must contain exactly one primary variant.

The primary variant:

• Appears as the default item in search results
• Provides the default image experience for the variant group
• Serves as the initial customer experience when shoppers open the item page

When selecting a primary variant, consider using the best-selling variation, the most common color or size, or the variant with the strongest inventory availability.

• Exactly one item in the group should be marked as the primary variant
• All other items should use "No"

Example:

"isPrimaryVariant": "Yes"

All other variants must use:

"isPrimaryVariant": "No"

variantAttributeNames

Identifies which attributes vary within the group.

• Up to three variant attributes can be used.
• The specified attribute must also exist in the item's Visible section.
• All items in the group must use the same attribute names.
• If a variant attribute is not present in the Visible section, the submission fails.

Example:

"variantAttributeNames": [ "color", "size"
]

swatchImages

Optional swatch images can be used for visual variant attributes such as color or pattern. Swatches help customers distinguish between variants directly on the item page.

Each swatch includes:

• swatchImageUrl – URL of the swatch image.
• swatchVariantAttribute – The variant attribute represented by the swatch (for example, color or pattern).

Supported variant attributes

Supported variant attributes vary by product type and item specification version. Refer to the item specification for your product type to determine which attributes support variant grouping.

Common variant attributes include:

• Color
• Size
• Pattern
• Character
• Count
• Count per pack
• Multipack quantity
• Theme

Example variant group (single attribute)

The following example creates a variant group for a toothpaste product that is available in two flavors.

• Both toothpaste items belong to the same variant group because they share the same variantGroupId.
• The products vary by the flavor attribute.
• Peppermint is designated as the primary variant.
• Spearmint is a secondary variant within the same group.

{ "MPItemFeedHeader": { "businessUnit": "WALMART_US", "locale": "en", "version": "2.0.20230221-12_22_32-api" }, "MPItem": [ { "Orderable": { "productId": "123456", "sku": "ABC123" }, "Visible": { "Toothpastes": { "productName": "Colgate Crest Toothpaste", "flavor": "Peppermint", "variantGroupId": "001960968586AX6", "isPrimaryVariant": "Yes", "variantAttributeNames": [ "flavor" ] } } }, { "Orderable": { "productId": "123456", "sku": "ABC1245" }, "Visible": { "Toothpastes": { "productName": "Colgate Crest Toothpaste", "flavor": "Spearmint", "variantGroupId": "001960968586AX6", "isPrimaryVariant": "No", "variantAttributeNames": [ "flavor" ] } } } ]
}

Example variant group (multiple attributes)

The following curtain product varies by both color and size.

All four items:

• Share the same variantGroupId
• Use the same variantAttributeNames
• Represent unique color and size combinations

Example:

"variantAttributeNames": [ "color", "size"
]

Best practices

• Use a consistent and unique variantGroupId.
• Submit all variants in the same feed whenever possible.
• Select a single primary variant for the group.
• Consider using the best-selling variation, the most common color or size, or the variant with the strongest inventory availability as the primary variant.
• Ensure all variant attributes are present in the Visible section.
• Use no more than three variant attributes.
• Keep product content consistent across all variants except for the attributes that vary.

View existing variant groups

You can retrieve variant information using:

• Catalog search API
• Get all items API
• Get an item API

Use these APIs to verify items belong to the expected variant group, confirm primary variant assignment, and review the variant attribute values returned by Walmart.

Responses may include variant-specific fields such as variantGroupId, isPrimary, and groupingAttributes, which can be used to verify variant group configuration.

Managing variants

Variant groups are currently created and updated through item setup and maintenance feeds.

• Use MP_ITEM when creating new items and variant groups.
• Use MP_MAINTENANCE when updating existing variant groups or adding new variants to an existing group.

Troubleshooting

If variant grouping issues persist after validating the feed, review item-level processing errors and contact Partner Support.

Related guides

• Create a new seller-fulfilled item
• Update my existing items
• Item search for the Walmart catalog
• Catalog search for the seller catalog