inventory APIv1.6.0

createOrReplaceInventoryItemGroup

PUT
/inventory_item_group/{inventoryItemGroupKey}
This call creates a new inventory item group or updates an existing inventory item group. It is up to sellers whether they want to create a complete inventory item group record right from the start, or sellers can provide only some information with the initial createOrReplaceInventoryItemGroup call, and then make one or more additional createOrReplaceInventoryItemGroup calls to complete the inventory item group record. Upon first creating an inventory item group record, the only required elements are the inventoryItemGroupKey identifier in the call URI, and the members of the inventory item group specified through the variantSKUs array in the request payload.

In the case of updating/replacing an existing inventory item group, this call does a complete replacement of the existing inventory item group record, so all fields (including the member SKUs) that make up the inventory item group are required, regardless of whether their values changed. So, when replacing/updating an inventory item group record, it is advised that the seller run a getInventoryItemGroup call for that inventory item group to see all of its current values/settings/members before attempting to update the record. And if changes are made to an inventory item group that is part of a live, multiple-variation eBay listing, these changes automatically update the eBay listing. For example, if a SKU value is removed from the inventory item group, the corresponding product variation will be removed from the eBay listing as well.

In addition to the required inventory item group identifier and member SKUs, other key information that is set with this call include:
  • Title and description of the inventory item group. The string values provided in these fields will actually become the listing title and listing description of the listing once the first SKU of the inventory item group is published successfully
  • Common aspects that inventory items in the qroup share
  • Product aspects that vary within each product variation
  • Links to images demonstrating the variations of the product, and these images should correspond to the product aspect that is set with the variesBy.aspectsImageVariesBy field

In addition to the authorization header, which is required for all eBay REST API calls, the createOrReplaceInventoryItemGroup call also requires the Content-Language header, that sets the natural language that will be used in the field values of the request payload. For US English, the code value passed in this header should be en-US. To view other supported Content-Language values, and to read more about all supported HTTP headers for eBay REST API calls, see the HTTP request headers topic in the Using eBay RESTful APIs document.

Input

Resource URI (production)

PUT https://api.ebay.com/sell/inventory/v1/inventory_item_group/{inventoryItemGroupKey}

URI parameters

ParameterTypeDescription
inventoryItemGroupKeystringUnique identifier of the inventory item group. This identifier is supplied by the seller. The inventoryItemGroupKey value for the inventory item group to create/update is passed in at the end of the call URI. This value cannot be changed once it is set.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

HeaderTypeDescription
Content-LanguagestringThis request header sets the natural language that will be provided in the field values of the request payload.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one scope from the following list:

https://api.ebay.com/oauth/api_scope/sell.inventory

See Oauth access tokens for more information.

Input container/fieldTypeDescription
aspectsobjectThis container consists of an array of aspects that are shared by all product variations within the inventory item group. Common aspects for the inventory item group are not immediately required upon creating an inventory item group, but these aspects will be required before the first offer of the group is published. Common aspects for a men's t-shirt might be pattern and sleeve length. See the example below to get an idea of the JSON syntax that is used to specify common aspects:
"aspects": {
"pattern": ["solid"],
"sleeves": ["short"]
}
This container is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.

Occurrence: Conditional

descriptionstringThe description of the inventory item group. This description should fully describe the product and the variations of the product that are available in the inventory item group since this description will ultimately become the listing description once the first offer of the group is published. This field is not initially required when first creating an inventory item group, but will be required before the first offer of the group is published.

Note: Since this description will ultimately become the listing description in a multiple-variation listing, the seller should omit the listingDescription field when creating the offers for each variation. If they include this listingDescription field, the text in this field will overwrite the text provided in this description field for the inventory item group.

This field is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.

Max Length: 500000

Occurrence: Conditional

inventoryItemGroupKeystringThis is the unique identifier of the inventory item group. This identifier is created by the seller when an inventory item group is created. This field is only applicable to the getInventoryItemGroup call and not to the createOrReplaceInventoryItemGroup call. In the createOrReplaceInventoryItemGroup call, the inventoryItemGroupKey value is passed into the end of the call URI instead.

Occurrence: NA

imageUrlsarray of stringAn array of one or more links to images for the inventory item group. URLs must use the "HTTPS" protocol. Images can be self-hosted by the seller, or sellers can use the UploadSiteHostedPictures call of the Trading API to upload images to an eBay Picture Server. If successful, the response of the UploadSiteHostedPictures call will contain a full URL to the image on an eBay Picture Server. This is the URL that will be passed in through the imageUrls array.

Before any offer can be published, at least one image must exist for the offer. Links to images can either be passed in through this imageUrls container, or they can be passed in through the product.imageUrls container when creating each inventory item in the group. If the variesBy.aspectsImageVariesBy field is used to specify the main product aspect where the variations vary, the links to the images must be passed in through this imageUrls container, and there should be a picture for each variation. So, if the variesBy.aspectsImageVariesBy field is set to Color, a link should be included to an image demonstrating each available color in the group.

Most eBay sites support up to 12 pictures free of charge, and eBay Motors listings can have up to 24 pictures.

This container will always be returned for an inventory item group that has at least one published offer since a published offer will always have at least one picture, but this container will only be returned if defined for inventory item groups that have yet to have any published offers.

Occurrence: Conditional

subtitlestringA subtitle is an optional listing feature that allows the seller to provide more information about the product, possibly including keywords that may assist with search results. An additional listing fee will be charged to the seller if a subtitle is used. For more information on using listing subtitles on the US site, see the Adding a subtitle to your listings help page.

Note: Since this subtitle will ultimately become the subtitle in a multiple-variation listing, the seller should not include the subtitle field when creating the inventory items that are members of the group. If they do include the subtitle field in an inventory item record, the text in that field will overwrite the text provided in this subtitle field for each inventory item in the group that is published.

This field will only be returned if set for an inventory item.

Max Length: 55

Occurrence: Conditional

titlestringThe title of the inventory item group. This title will ultimately become the listing title once the first offer of the group is published. This field is not initially required when first creating an inventory item group, but will be required before the first offer of the group is published.

Note: Since this title will ultimately become the listing title in a multiple-variation listing, the seller should omit the title field when creating the inventory items that are members of the group. If they do include the title field in an inventory item record, the text in that field will overwrite the text provided in this title field for each inventory item in the group that is published.

This field is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.

Max Length: 80

Occurrence: Conditional

variantSKUsarray of stringThis required container is used to assign individual inventory items to the inventory item group. Multiple SKU values are passed in to this container. If updating an existing inventory item group, the seller should make sure that all member SKU values are passed in, as long as the seller wants that SKU to remain in the group.

It is also possible to add or remove SKUs with a createOrReplaceInventoryItemGroup call. If the seller wants to remove a SKU from the group, that seller will just omit that SKU value from this container to remove that inventory item/SKU from the inventory item group and any published, multiple-variation listing. However, a variation cannot be removed from the group if that variation has one or more sales for that listing. A workaround for this is to set that variation's quantity to 0 and it will be 'grayed out' in the View Item page.

This container is always returned.

Occurrence: Required

variesByVariesByThis container is used to specify product aspects for which variations within an inventory item group vary, and a complete list of all those variances. For example, t-shirts in an inventory item group may be available in multiple sizes and colors. If this is the case, Color and Size would both be values in the specifications.name fields, and the available colors and sizes would be values under the corresponding specifications.values array. If the seller will be including multiple images in the listing that will demonstrate how each variation differs, that seller will also include the aspectsImageVariesBy field, and call out the product aspect where the listing images differ. In the t-shirts example, this product aspect would be Color, and the seller could either include URLs to images of the t-shirt (in available colors) through the inventory item group entity, or the seller could also included URLs to images of the t-shirt through the individual inventory item entities of the group.

This container is not initially required when first creating an inventory item group, but the variesBy.specifications container will be required before the first offer of the group is published.

This container is always returned if one or more offers associated with the inventory item group have been published, and is only returned if set for an inventory item group if that group has yet to have any offers published.

Occurrence: Conditional

variesBy.aspectsImageVariesByarray of stringThis container is used if the seller wants to include multiple images to demonstrate how variations within a multiple-variation listing differ. In this string field, the seller will specify the product aspect where the variations of the inventory item group vary, such as color. If Color is specified in this field, Color must also be one of the specifications.name values, and all available colors must appear in the corresponding specifications.values array.

If the aspectsImageVariesBy container is used, links to images of each variation should be specified through the imageUrls container of the inventory item group, or the seller can choose to include those links to images in each inventory item record for the inventory items in the group.

Occurrence: Conditional

variesBy.specificationsarray of SpecificationThis container consists of an array of one or more product aspects where each variation differs, and values for each of those product aspects. This container is not immediately required, but will be required before the first offer of the inventory item group is published.

If a product aspect is specified in the aspectsImageVariesBy container, this product aspect (along with all variations of that product aspect) must be included in the specifications container. Before offers related to the inventory item group are published, the product aspects and values specified through the specifications container should be in synch with the name-value pairs specified through the product.aspects containers of the inventory items contained in the group. For example, if Color and Size are in this specifications container, each inventory item of the group should also have Color and Size as aspect names in their inventory item records.

This container is always returned if one or more offers associated with the inventory item group have been published. For inventory item groups that have yet to have any published offers, this container is only returned if set.

Occurrence: Conditional

variesBy.specifications.namestringThis is the name of product variation aspect. Typically, for clothing, typical aspect names are "Size" and "Color". Product variation aspects are not required immediately upon creating an inventory item group, but these aspects will be required before a multiple-variation listing containing this inventory item group is published. For each product variation aspect that is specified through the specifications container, one name value is required and two or more variations of this aspect are required through the values array.

Note: Each member of the inventory item group should have these same aspect names specified through the product.aspects container when the inventory item is created with the createOrReplaceInventoryItem or bulkCreateOrReplaceInventoryItem call.
Max Length: 40

Occurrence: Conditional

variesBy.specifications.valuesarray of stringThis is an array of values pertaining to the corresponding product variation aspect (specified in the name field). Below is a sample of how these values will appear under a specifications container:
"specifications": [{
"name": "Size",
"values": ["Small",
"Medium",
"Large"]
},
{
"name": "Color",
"values": ["Blue",
"White",
"Red"]
}]
Note: Each member of the inventory item group should have these same aspect names, and each individual inventory item should have each variation of the product aspect values specified through the product.aspects container when the inventory item is created with the createOrReplaceInventoryItem or bulkCreateOrReplaceInventoryItem call.
Max Length: 50

Occurrence: Conditional

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
Content-LanguageThis describes the natural language(s) of the intended audience for the enclosed entity
Output container/fieldTypeDescription
warningsarray of ErrorDetailV3This container will be returned in a call response payload if one or more warnings or errors are triggered when an Inventory API call is made. This container will contain detailed information about the error or warning.

Occurrence: Conditional

warnings.errorIdintegerA unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.domainstringThe name of the domain in which the error or warning occurred.

Occurrence: Conditional

warnings.subdomainstringThe name of the subdomain in which the error or warning occurred.

Occurrence: Conditional

warnings.categorystringThis string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Conditional

warnings.messagestringA description of the condition that caused the error or warning.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3Various warning and error messages return one or more variables that contain contextual information about the error or waring. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

warnings.parameters.valuestringThis is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.parameters.namestringThis is the name of input field that caused an issue with the call request.

Occurrence: Conditional

warnings.longMessagestringA detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

warnings.inputRefIdsarray of stringAn array of one or more reference IDs which identify the specific request element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.outputRefIdsarray of stringAn array of one or more reference IDs which identify the specific response element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200Success
201Created
204No Content
400Bad Request
500Internal Server Error

Error codes

CodeDomainCategoryMeaning
25001API_INVENTORYAPPLICATIONA system error has occurred. {additionalInfo}
25002API_INVENTORYREQUESTA user error has occurred. {additionalInfo}
25003API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}
25004API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}
25005API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}
25006API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}
25007API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}
25008API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}
25009API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}
25011API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}
25012API_INVENTORYREQUESTInvalid inventory location. {additionalInfo}
25013API_INVENTORYREQUESTInvalid data in the Inventory Item Group. {additionalInfo}
25014API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}
25015API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}
25016API_INVENTORYREQUESTThe {fieldName} value is invalid. {additionalInfo}
25017API_INVENTORYREQUEST{fieldName} is missing. {additionalInfo}
25018API_INVENTORYREQUESTIncomplete account information. {additionalInfo}
25019API_INVENTORYREQUESTCannot revise listing. {additionalInfo}
25020API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}
25021API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}
25022API_INVENTORYREQUESTInvalid attribute. {fieldName}
25023API_INVENTORYREQUESTInvalid compatibility information. {additionalInfo}
25024API_INVENTORYREQUESTInvalid Best Offer information. {additionalInfo}
25025API_INVENTORYAPPLICATIONConcurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later.
25026API_INVENTORYREQUESTSelling limit exceeded. {additionalInfo}
25701API_INVENTORYREQUESTOne or more of the supplied SKU(s) could not be found in the system.
25702API_INVENTORYREQUEST{skuValue} could not be found or is not available in the system.
25703API_INVENTORYREQUESTThe following SKU is already a member of another group. SKU : {skuValue} groupId : {inventoryItemGroupKey}
25704API_INVENTORYREQUESTThe following SKU is already listed as a single SKU listing. SKU : {skuValue} Listing ID : {listingId}
25705API_INVENTORYREQUESTThe Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system.
25709API_INVENTORYREQUESTInvalid value for {fieldName}. {additionalInfo}

Samples

New to making API calls? Please see Making a Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample 1: Creating an Inventory Item Group

This call will create an inventory item group for the seller's acount.

Input

The inventoryItemGroupKey value associated with the inventory item group to create is input into the end of the call URI. In this case, the inventoryItemGroupKey value for the inventory item group is Mens_Solid_Polo_Shirts.

This particular inventory item group will be composed of men's solid polo shirts in five different colors and four different sizes. The common product aspects that each inventory item of the group shares is the pattern and the sleeve size, as specified in the aspects container. The full list of inventory items that will become part of this group is specified through the variantSKUs container. Note that inventory item records must already exist for all of these SKU values in order for the inventory item group to be created. The particular aspect where images of the shirt variations will vary is stated in the aspectsImageVariesBy container. In this particular case, an image of a shirt in each available color will be part of the listing. The available colors (and sizes) of the shirts are specified under the specifications container.
PUT
https://api.ebay.com/sell/inventory/v1/inventory_item_group/Mens_Solid_Polo_Shirts

Output

There is no output payload with this response. A successful call contains an HTTP status code of 200.