PUT/inventory_item_group/{inventoryItemGroupKey}
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.
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.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Inventory item group fields for a list of fields required to publish an offer.
Note: In addition to the
authorization
header, which is required for all Inventory API calls, this call also requires the Content-Type
and Content-Language
headers. See the HTTP request headers for more information.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 group 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
Note: For more information, see Creating and managing inventory item groups.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com
root URI with api.sandbox.ebay.com
URI parameters
Parameter | Type | Description |
---|---|---|
inventoryItemGroupKey | string | This path parameter specifies the unique identifier of the inventory item group being created or updated. This identifier is defined by the seller. This value cannot be changed once it is set. Max Length: 50 Occurrence: Required |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization
HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
Header | Type | Description |
---|---|---|
Content-Language | string | This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.For more information on the Content-Language header, refer to HTTP request headers. Occurrence: Required |
Content-Type | string | This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required |
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/sell.inventory
See OAuth access tokens for more information.
Request payload
Copy complete valid JSON to clipboardRequest fields
Input container/field | Type | Description |
---|---|---|
aspects | string | This is a collection of item specifics (aka product aspects) name-value pairs 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. Below is an example of the proper JSON syntax to use when manually inputting item specifics. Note that one item specific name, such as 'Features', can have more than one value. If an item specific name has more than one value, each value is delimited with a comma. 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.Important!Publish offer note: This field is required before an offer can be published to create an active listing. Occurrence: Conditional |
description | string | The 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. Important!Publish offer note: This field is required before an offer can be published to create an active listing. Max Length: 500000 (which includes HTML markup/tags) Occurrence: Conditional |
imageUrls | array of string | An 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. Occurrence: Conditional |
inventoryItemGroupKey | string | This is the unique identifier of the inventory item group. This identifier is created by the seller when an inventory item group is created. Occurrence: NA |
subtitle | string | A 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. Occurrence: Conditional |
title | string | The 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. Important!Publish offer note: This field is required before an offer can be published to create an active listing. Max Length: 80 Occurrence: Conditional |
variantSKUs | array of string | This 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. Occurrence: Required |
variesBy | VariesBy | This 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, Important!Publish offer note: This container and its child fields (as noted below) are required before an offer can be published to create an active listing. Occurrence: Conditional |
variesBy.aspectsImageVariesBy | array of string | This 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 Important!Publish offer note: This array is required and at least one aspect (such as Occurrence: Conditional |
variesBy.specifications | array of Specification | This 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. Important!Publish offer note: This array is required and at least one aspect with the available variations must be specified. Occurrence: Conditional |
variesBy.specifications.name | string | This is the name of product variation aspect. Typically, for clothing, typical aspect names are Important!Publish offer note: This field is required before an offer can be published to create an active listing. Max Length: 40 Occurrence: Conditional |
variesBy.specifications.values | array of string | This 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: 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. Important!Publish offer note: This array is required and at least one value that matches the corresponding aspect name must be specified. Max Length: 50 Occurrence: Conditional |
videoIds | array of string | An array of one or more videoId values for the inventory item group. A video ID is a unique identifier that is automatically created by eBay when a seller successfully uploads a video to eBay using the uploadVideo method of the Media API. Occurrence: Optional |
Output
HTTP response headers
See HTTP response headers for details.
Header | Meaning |
---|---|
Content-Language | This describes the natural language(s) of the intended audience for the enclosed entity |
Response payload
Response fields
Output container/field | Type | Description |
---|---|---|
warnings | array of ErrorDetailV3 | This 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.category | string | This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. Occurrence: Conditional |
warnings.domain | string | The name of the domain in which the error or warning occurred. Occurrence: Conditional |
warnings.errorId | integer | A 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.inputRefIds | array of string | An 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.longMessage | string | A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem. Occurrence: Conditional |
warnings.message | string | A description of the condition that caused the error or warning. Occurrence: Conditional |
warnings.outputRefIds | array of string | An 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 |
warnings.parameters | array of ErrorParameterV3 | Various 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.name | string | This type contains the name and value of an input parameter that contributed to a specific error or warning condition. Occurrence: Conditional |
warnings.parameters.value | string | This is the actual value that was passed in for the element specified in the name field. Occurrence: Conditional |
warnings.subdomain | string | The name of the subdomain in which the error or warning occurred. 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.
Status | Meaning |
---|---|
200 | Success |
201 | Created |
204 | No Content |
400 | Bad Request |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
25001 | API_INVENTORY | APPLICATION | A system error has occurred. {additionalInfo} |
25002 | API_INVENTORY | REQUEST | A user error has occurred. {additionalInfo} |
25003 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo} |
25004 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo} |
25005 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo} |
25006 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo} |
25007 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo} |
25008 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo} |
25009 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo} |
25011 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo} |
25012 | API_INVENTORY | REQUEST | Invalid inventory location. {additionalInfo} |
25013 | API_INVENTORY | REQUEST | Invalid data in the Inventory Item Group. {additionalInfo} |
25014 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo} |
25015 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo} |
25016 | API_INVENTORY | REQUEST | The {fieldName} value is invalid. {additionalInfo} |
25017 | API_INVENTORY | REQUEST | {fieldName} is missing. {additionalInfo} |
25018 | API_INVENTORY | REQUEST | Incomplete account information. {additionalInfo} |
25019 | API_INVENTORY | REQUEST | Cannot revise listing. {additionalInfo} |
25020 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo} |
25021 | API_INVENTORY | REQUEST | The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo} |
25022 | API_INVENTORY | REQUEST | Invalid attribute. {fieldName} |
25023 | API_INVENTORY | REQUEST | Invalid compatibility information. {additionalInfo} |
25024 | API_INVENTORY | REQUEST | Invalid Best Offer information. {additionalInfo} |
25025 | API_INVENTORY | APPLICATION | Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later. |
25026 | API_INVENTORY | REQUEST | Selling limit exceeded. {additionalInfo} |
25041 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s). |
25042 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, free shipping must be provided. |
25043 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, returns must be accepted. |
25044 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, refund must be provided as Money Back. |
25045 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days. |
25046 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, seller must pay the cost for return shipping. |
25047 | API_INVENTORY | REQUEST | Seller is not eligible to use Refurbished Item Condition |
25048 | API_INVENTORY | REQUEST | Seller is not eligible to use Refurbished Item Condition in this Category |
25049 | API_INVENTORY | REQUEST | Seller is not eligible to use Refurbished Item Condition for the selected Brand |
25050 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title. |
25051 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle |
25052 | API_INVENTORY | REQUEST | When listing an item with Refurbished condition, at least {replaceable_value} images must be provided |
25097 | API_INVENTORY | REQUEST | This listing is on hold due to a policy violation, and revisions are not possible. Please check your email for more information. |
25098 | API_INVENTORY | REQUEST | {replaceable_value} transaction is not possible as the parent listing is on-hold. Please check your email for further information. |
25701 | API_INVENTORY | REQUEST | One or more of the supplied SKU(s) could not be found in the system. |
25702 | API_INVENTORY | REQUEST | {skuValue} could not be found or is not available in the system. |
25703 | API_INVENTORY | REQUEST | The following SKU is already a member of another group. SKU : {skuValue} groupId : {inventoryItemGroupKey} |
25704 | API_INVENTORY | REQUEST | The following SKU is already listed as a single SKU listing. SKU : {skuValue} Listing ID : {listingId} |
25705 | API_INVENTORY | REQUEST | The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system. |
25709 | API_INVENTORY | REQUEST | Invalid value for {fieldName}. {additionalInfo} |
25756 | API_INVENTORY | REQUEST | Auction format is not permitted with a SKU that is part of an InventoryItemGroup. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
25096 | API_INVENTORY | REQUEST | This listing is on hold due to a policy violation. You may revise it to resolve the situation. Please check your email for more information. |
25401 | API_INVENTORY | APPLICATION | Invalid listing format removed {additionalInfo} |
25402 | API_INVENTORY | APPLICATION | System warning. {additionalInfo} |
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant 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_********_Shirts
.
This particular inventory item group will be composed of Men's ******** 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.
PUThttps://api.ebay.com/sell/inventory/v1/inventory_item_group/Mens_********_Shirts
Output
A successful call returns an HTTP status code of 204 and has no response payload.