Create/Update Product Variant Groups

Create or Update Variant Groups for your products.

This API endpoint allows sellers to create or update product variant groups by defining the variant structure (such as Size, Color, Style) and associating multiple product listings under a unified group. Each variant group can support up to three option levels, and each product variant is uniquely identified by its SellerPartNumber.

The request payload contains two main sections:

• Variants: A list of products with their respective option values (e.g., Small, Red, Advanced).
• Options: A list of option definitions (e.g., Size, Color) and their valid values.

The API performs strict validation:

• SellerPartNumber and Option1 are required for each variant.
• Option values must match the predefined values in the Options list.
• Variants with duplicate combinations of option values are not allowed.

On successful execution, the API returns a unique ItemGroupID and a list of mapping statuses between each variant and its assigned parent item.

This endpoint is typically used for managing product listings with multiple variants under one logical group on the marketplace.

Resource URL

Newegg.com: https://api.newegg.com /marketplace/contentmgmt/item/group-product-variants?sellerid={sellerid}
Newegg.ca: https://api.newegg.com /marketplace/can/contentmgmt/item/group-product-variants?sellerid={sellerid}

Note: Please make sure your request URL is all in lower case (except for Seller ID) and cannot contain any blank spaces or line breaks.

Parameters

Name	Required?	Description
sellerid	Yes	Your seller ID on Newegg Marketplace

 

Resource Information

HTTP Method	Authentication?	Request Formats	Response Formats	Rate Limited?
POST	Required	XML, Json	XML, Json	10,000 request per hour

 

Request Body

Attribute	Required?	Format	Description
Variants	Yes	List<Variant>	The list of product variants in the group.
Variant.SellerPartNumber	Yes	String	Unique identifier for the variant.
Variant.Option1	Yes	String	First variant option (e.g., Size). Must match an option. Max characters: 30
Variant.Option2	No	String	Second variant option (e.g., Color). Max characters: 30
Variant.Option3	No	String	Third variant option (e.g., Style). Max characters: 30
Options	No	List<Option>	Defines available option types and values. Max: 3
Option.Name	Yes	String	Option type name (e.g., Size, Color). Max characters: 30
Option.OptionValues	Yes	List<String>	Valid values for this option (e.g., Small, Medium).

 

Schema: CreateAndUpdateVariantGroupRequest.xsd

Example: XML, Request

<Grouping>
    <Variants>
        <Variant>
            <SellerPartNumber>as_20250520_0938</SellerPartNumber>
            <Option1>Small</Option1>
            <Option2>Advanced</Option2>
            <Option3></Option3>
        </Variant>
        <Variant>
            <SellerPartNumber>as_20250520_0939</SellerPartNumber>
            <Option1>Medium</Option1>
            <Option2>Advanced</Option2>
            <Option3></Option3>
        </Variant>
        <Variant>
            <SellerPartNumber>as_20250520_0937</SellerPartNumber>
            <Option1>Small</Option1>
            <Option2>Extral</Option2>
            <Option3></Option3>
        </Variant>
    </Variants>
    <Options>
        <Option>
            <Name>Size</Name>
            <OptionValues>
                <Value>Small</Value>
                <Value>Medium</Value>
            </OptionValues>
        </Option>
        <Option>
            <Name>Mode</Name>
            <OptionValues>
                <Value>Advanced</Value>
                <Value>Extral</Value>
            </OptionValues>
        </Option>
    </Options>
</Grouping>

 

Example: Json, Request

{
    "Variants": [
        {
            "SellerPartNumber": "as_20250520_0938",
            "Option1": "Small",
            "Option2": "Advanced"
        },
        {
            "SellerPartNumber": "as_20250520_0939",
            "Option1": "Medium",
            "Option2": "Advanced"
        },
        {
            "SellerPartNumber": "as_20250520_0937",
            "Option1": "Small",
            "Option2": "Extral"
        }
    ],
    "Options": [
        {
            "Name": "Size",
            "OptionValues": [
                "Small",
                "Medium"
            ]
        },
        {
            "Name": "Mode",
            "OptionValues": [
                "Advanced",
                "Extral"
            ]
        }
    ]
}

 

Response Body

Attribute	Format	Description
ItemGroupID	Int	The unique identifier for the created or updated product variant group.
ItemVariantGroupStatusList	List<ItemVariantStatus>	A list of results for each item in the variant group.
ItemVariantGroupStatusList[].ItemNumber	String	The unique platform-assigned identifier for the item (SKU).
ItemVariantGroupStatusList[].IsSuccess	boolean	Indicates whether this specific item was successfully grouped or updated.
IsSuccess	boolean	Overall result of the group creation/update operation. true = success.

 

Example: XML, Response

<?xml version="1.0" encoding="utf-16"?>
<VariantGroupResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItemGroupID>2110011075</ItemGroupID>
    <ItemVariantGroupStatusList>
        <ItemVariantGroupStatus>
            <ItemNumber>9SIBE0E0001845</ItemNumber>
            <ItemGroupID>2110011075</ItemGroupID>
            <IsSuccess>true</IsSuccess>
        </ItemVariantGroupStatus>
        <ItemVariantGroupStatus>
            <ItemNumber>9SIBE0E0001843</ItemNumber>
            <ItemGroupID>2110011075</ItemGroupID>
            <IsSuccess>true</IsSuccess>
        </ItemVariantGroupStatus>
        <ItemVariantGroupStatus>
            <ItemNumber>9SIBE0E0001847</ItemNumber>
            <ItemGroupID>2110011075</ItemGroupID>
            <IsSuccess>true</IsSuccess>
        </ItemVariantGroupStatus>
    </ItemVariantGroupStatusList>
    <IsSuccess>true</IsSuccess>
</VariantGroupResponse>

 

Example: JSON, Response

{
    "ItemGroupID": 2110011075,
    "ItemVariantGroupStatusList": [
        {
            "ItemNumber": "9SIBE0E0001845",
            "IsSuccess": true
        },
        {
            "ItemNumber": "9SIBE0E0001843",
            "IsSuccess": true
        },
        {
            "ItemNumber": "9SIBE0E0001847",
            "IsSuccess": true
        }
    ],
    "IsSuccess": true
}

 

Request Failure Errors

For common HTTP error responses, please refer to Failed Response Error Code List.

Error Code	Description
CE003	Validation failed: SellerPartNumber cannot be empty.
CE027	System Error, please try again. If problem persists, please contact Marketplace Support.

 

Example: XML, Response

<?xml version="1.0" encoding="utf-8"?>
<Errors xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Mkpl.Sdk.Core.Api.Entity">
    <Error>
        <Code>CE003</Code>
        <Message>Validation failed: SellerPartNumber cannot be empty.</Message>
    </Error>
</Errors>

Example: JSON, Response

[
    {
        "Code": "CE003",
        "Message": "Validation failed: SellerPartNumber cannot be empty."
    }
]