openapi: 3.0.0
info:
title: eBay Account Advertising_eligibility Inventory_item_group API
description: The <b>Account API</b> gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information. <br><br>For details on the availability of the methods in this API, see <a href="/api-docs/sell/account/overview.html#requirements">Account API requirements and restrictions</a>.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.9.2
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/account/v1
tags:
- name: Inventory_item_group
paths:
/inventory_item_group/{inventoryItemGroupKey}:
get:
tags:
- Inventory_item_group
description: This call retrieves the inventory item group for a given <strong>inventoryItemGroupKey</strong> value. The <strong>inventoryItemGroupKey</strong> value is passed in at the end of the call URI.
operationId: getInventoryItemGroup
parameters:
- name: inventoryItemGroupKey
in: path
description: This path parameter specifies the unique identifier of the inventory item group being retrieved. This value is assigned by the seller when an inventory item group is created.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/InventoryItemGroup'
'400':
description: Bad Request
x-response-codes:
errors:
'25705':
domain: API_INVENTORY
category: REQUEST
description: The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system.
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid value for {fieldName}. {additionalInfo}
'25710':
domain: API_INVENTORY
category: REQUEST
description: We didn't find the resource/entity you are requesting. Please verify the request
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: A system error has occurred. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory.readonly
- https://api.ebay.com/oauth/api_scope/sell.inventory
put:
tags:
- Inventory_item_group
description: '<span class="tablenote"><strong>Note:</strong> 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.</span><br>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 <strong>createOrReplaceInventoryItemGroup</strong> call, and then make one or more additional <strong>createOrReplaceInventoryItemGroup</strong> calls to complete the inventory item group record. Upon first creating an inventory item group record, the only required elements are the <strong>inventoryItemGroupKey</strong> identifier in the call URI, and the members of the inventory item group specified through the <strong>variantSKUs</strong> array in the request payload.<br><br><span class="tablenote"><b>Note:</b> In addition to the <code>authorization</code> header, which is required for all Inventory API calls, this call also requires the <code>Content-Type</code> and <code>Content-Language</code> headers. See the <a href="/api-docs/sell/inventory/resources/inventory_item_group/methods/createOrReplaceInventoryItemGroup#h3-request-headers">HTTP request headers</a> for more information.</span><br>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 <strong>getInventoryItemGroup</strong> 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.<br><br> In addition to the required inventory item group identifier and member SKUs, other key information that is set with this call include: <ul> <li>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</li> <li>Common aspects that inventory items in the group share</li> <li>Product aspects that vary within each product variation</li> <li>Links to images demonstrating the variations of the product, and these images should correspond to the product aspect that is set with the <strong>variesBy.aspectsImageVariesBy</strong> field</li> </ul>'
operationId: createOrReplaceInventoryItemGroup
parameters:
- name: Content-Language
in: header
description: 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 <code>en-US</code> for English or <code>de-DE</code> for German.<br><br>For more information on the Content-Language header, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
- name: inventoryItemGroupKey
in: path
description: This path parameter specifies the unique identifier of the inventory item group being created or updated. This identifier is defined by the seller.<br><br>This value cannot be changed once it is set.<br><br><b>Max Length:</b> 50
required: true
schema:
type: string
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: Details of the inventory Item Group
content:
application/json:
schema:
description: Details of the inventory Item Group
$ref: '#/components/schemas/InventoryItemGroup'
required: true
responses:
'200':
description: Success
headers:
Content-Language:
schema:
type: string
description: This describes the natural language(s) of the intended audience for the enclosed entity
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
x-response-codes:
errors:
'25401':
domain: API_INVENTORY
category: APPLICATION
description: Invalid listing format removed {additionalInfo}
'25402':
domain: API_INVENTORY
category: APPLICATION
description: System warning. {additionalInfo}
'201':
description: Created
headers:
Content-Language:
schema:
type: string
description: This describes the natural language(s) of the intended audience for the enclosed entity
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
x-response-codes:
errors:
'25401':
domain: API_INVENTORY
category: APPLICATION
description: Invalid listing format removed {additionalInfo}
'25402':
domain: API_INVENTORY
category: APPLICATION
description: System warning. {additionalInfo}
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'25002':
domain: API_INVENTORY
category: REQUEST
description: A user error has occurred. {additionalInfo}
'25003':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}
'25004':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}
'25005':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}
'25006':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}
'25007':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}
'25008':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}
'25009':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}
'25011':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}
'25012':
domain: API_INVENTORY
category: REQUEST
description: Invalid inventory location. {additionalInfo}
'25013':
domain: API_INVENTORY
category: REQUEST
description: Invalid data in the Inventory Item Group. {additionalInfo}
'25014':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}
'25015':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}
'25016':
domain: API_INVENTORY
category: REQUEST
description: The {fieldName} value is invalid. {additionalInfo}
'25017':
domain: API_INVENTORY
category: REQUEST
description: '{fieldName} is missing. {additionalInfo}'
'25018':
domain: API_INVENTORY
category: REQUEST
description: Incomplete account information. {additionalInfo}
'25019':
domain: API_INVENTORY
category: REQUEST
description: Cannot revise listing. {additionalInfo}
'25020':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}
'25021':
domain: API_INVENTORY
category: REQUEST
description: The eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}
'25022':
domain: API_INVENTORY
category: REQUEST
description: Invalid attribute. {fieldName}
'25023':
domain: API_INVENTORY
category: REQUEST
description: Invalid compatibility information. {additionalInfo}
'25024':
domain: API_INVENTORY
category: REQUEST
description: Invalid Best Offer information. {additionalInfo}
'25026':
domain: API_INVENTORY
category: REQUEST
description: Selling limit exceeded. {additionalInfo}
'25041':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s).
'25042':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, free shipping must be provided.
'25043':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, returns must be accepted.
'25044':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, refund must be provided as Money Back.
'25045':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days.
'25046':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, seller must pay the cost for return shipping.
'25047':
domain: API_INVENTORY
category: REQUEST
description: Seller is not eligible to use Refurbished Item Condition
'25048':
domain: API_INVENTORY
category: REQUEST
description: Seller is not eligible to use Refurbished Item Condition in this Category
'25049':
domain: API_INVENTORY
category: REQUEST
description: Seller is not eligible to use Refurbished Item Condition for the selected Brand
'25050':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title.
'25051':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle
'25052':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, at least {replaceable_value} images must be provided
'25701':
domain: API_INVENTORY
category: REQUEST
description: One or more of the supplied SKU(s) could not be found in the system.
'25702':
domain: API_INVENTORY
category: REQUEST
description: '{skuValue} could not be found or is not available in the system.'
'25703':
domain: API_INVENTORY
category: REQUEST
description: 'The following SKU is already a member of another group. SKU : {skuValue} groupId : {inventoryItemGroupKey}'
'25704':
domain: API_INVENTORY
category: REQUEST
description: 'The following SKU is already listed as a single SKU listing. SKU : {skuValue} Listing ID : {listingId}'
'25705':
domain: API_INVENTORY
category: REQUEST
description: The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system.
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid value for {fieldName}. {additionalInfo}
'25756':
domain: API_INVENTORY
category: REQUEST
description: Auction format is not permitted with a SKU that is part of an InventoryItemGroup.
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: A system error has occurred. {additionalInfo}
'25025':
domain: API_INVENTORY
category: APPLICATION
description: Concurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
delete:
tags:
- Inventory_item_group
description: This call deletes the inventory item group for a given <strong>inventoryItemGroupKey</strong> value.
operationId: deleteInventoryItemGroup
parameters:
- name: inventoryItemGroupKey
in: path
description: This path parameter specifies the unique identifier of the inventory item group being deleted. This value is assigned by the seller when an inventory item group is created.
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'25705':
domain: API_INVENTORY
category: REQUEST
description: The Inventory Item Group named {inventoryItemGroupKey} could not be found or is not available in the system.
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid value for {fieldName}. {additionalInfo}
'25710':
domain: API_INVENTORY
category: REQUEST
description: We didn't find the resource/entity you are requesting. Please verify the request
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: A system error has occurred. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
components:
schemas:
Specification:
type: object
properties:
name:
type: string
description: 'This is the name of product variation aspect. Typically, for clothing, typical aspect names are <code>"Size"</code> and <code>"Color"</code>. 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 <strong>specifications</strong> container, one <strong>name</strong> value is required and two or more variations of this aspect are required through the <strong>values</strong> array.<br><br> <span class="tablenote"> <strong>Note:</strong> Each member of the inventory item group should have these same aspect names specified through the <strong>product.aspects</strong> container when the inventory item is created with the <strong>createOrReplaceInventoryItem</strong> or <strong>bulkCreateOrReplaceInventoryItem</strong> call. </span><br><strong>Max Length</strong>: 40'
values:
type: array
description: 'This is an array of values pertaining to the corresponding product variation aspect (specified in the <strong>name</strong> field). Below is a sample of how these values will appear under a <strong>specifications</strong> container: <br> <pre><code>"specifications": [{<br> "name": "Size",<br> "values": ["Small",<br> "Medium",<br> "Large"]<br> },<br> { <br> "name": "Color",<br> "values": ["Blue",<br> "White",<br> "Red"] <br> }] </pre></code><span class="tablenote"> <strong>Note:</strong> 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 <strong>product.aspects</strong> container when the inventory item is created with the <strong>createOrReplaceInventoryItem</strong> or <strong>bulkCreateOrReplaceInventoryItem</strong> call. </span><br><strong>Max Length</strong>: 50'
items:
type: string
description: This type is used to specify product aspects for which variations within an inventory item group vary, and the order in which they appear in the listing. For example, t-shirts in an inventory item group may be available in multiple sizes and colors.
ErrorParameter:
type: object
properties:
name:
type: string
description: This type contains the name and value of an input parameter that contributed to a specific error or warning condition.
value:
type: string
description: This is the actual value that was passed in for the element specified in the <strong>name</strong> field.
description: This type is used to indicate the parameter field/value that caused an issue with the call request.
VariesBy:
type: object
properties:
aspectsImageVariesBy:
type: array
description: 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 <code>Color</code> is specified in this field, <code>Color</code> must also be one of the <strong>specifications.name</strong> values, and all available colors must appear in the corresponding <strong>specifications.values</strong> array.<br><br>If the <strong>aspectsImageVariesBy</strong> container is used, links to images of each variation should be specified through the <strong>imageUrls</strong> 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.
items:
type: string
specifications:
type: array
description: 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. <br><br>If a product aspect is specified in the <strong>aspectsImageVariesBy</strong> container, this product aspect (along with all variations of that product aspect) must be included in the <strong>specifications</strong> container. Before offers related to the inventory item group are published, the product aspects and values specified through the <strong>specifications</strong> container should be in synch with the name-value pairs specified through the <strong>product.aspects</strong> containers of the inventory items contained in the group. For example, if <code>Color</code> and <code>Size</code> are in this <strong>specifications</strong> container, each inventory item of the group should also have <code>Color</code> and <code>Size</code> as aspect names in their inventory item records.<br><br>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.
items:
$ref: '#/components/schemas/Specification'
description: This type is used to specify the product aspect(s) where individual items of the group vary, as well as a list of the available variations of those aspects.
InventoryItemGroup:
type: object
properties:
aspects:
type: string
description: '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.<br> <pre><code>"aspects": {<br> "pattern": ["solid"],<br> "sleeves": ["short"]<br> }</code></pre>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.<br>'
description:
type: string
description: '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. <br><br><span class="tablenote"> <strong>Note:</strong> Since this description will ultimately become the listing description in a multiple-variation listing, the seller should omit the <strong>listingDescription</strong> field when creating the offers for each variation. If they include the <strong>listingDescription</strong> field for the individual offer(s) in an item group, the text in that field for a published offer will overwrite the text provided in this <strong>description</strong> field for the inventory item group.</span><br><br>HTML tags and markup can be used in this field, but each character counts toward the max length limit.<br><br><span class="tablenote"> <strong>Note:</strong> To ensure that their short listing description is optimized when viewed on mobile devices, sellers should strongly consider using eBay''s <a href="https://pages.ebay.com/sell/itemdescription/customizeyoursummary.html " target="_blank">View Item description summary feature</a> when listing their items. Keep in mind that the ''short'' listing description is what prospective buyers first see when they view the listing on a mobile device. The ''full'' listing description is also available to mobile users when they click on the short listing description, but the full description is not automatically optimized for viewing in mobile devices, and many users won''t even drill down to the full description.<br><br> Using HTML div and span tag attributes, this feature allows sellers to customize and fully control the short listing description that is displayed to prospective buyers when viewing the listing on a mobile device. The short listing description on mobile devices is limited to 800 characters, and whenever the full listing description (provided in this field, in UI, or seller tool) exceeds this limit, eBay uses a special algorithm to derive the best possible short listing description within the 800-character limit. However, due to some short listing description content being removed, it is definitely not ideal for the seller, and could lead to a bad buyer experience and possibly to a Significantly not as described (SNAD) case, since the buyer may not get complete details on the item when viewing the short listing description. See the eBay help page for more details on using the HTML div and span tags.</span><br><br>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.<br><br><strong>Max Length</strong>: 500000 (which includes HTML markup/tags)<br>'
imageUrls:
type: array
description: 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 <a href="/Devzone/XML/docs/Reference/eBay/UploadSiteHostedPictures.html " target="_blank">UploadSiteHostedPictures</a> call of the Trading API to upload images to an eBay Picture Server. If successful, the response of the <a href="/Devzone/XML/docs/Reference/eBay/UploadSiteHostedPictures.html " target="_blank">UploadSiteHostedPictures</a> 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 <strong>imageUrls</strong> array. <br><br> 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 <strong>imageUrls</strong> container, or they can be passed in through the <strong>product.imageUrls</strong> container when creating each inventory item in the group. If the <strong>variesBy.aspectsImageVariesBy</strong> field is used to specify the main product aspect where the variations vary, the links to the images must be passed in through this <strong>imageUrls</strong> container, and there should be a picture for each variation. So, if the <strong>variesBy.aspectsImageVariesBy</strong> field is set to <code>Color</code>, a link should be included to an image demonstrating each available color in the group.<br><br>In almost any category at no cost, sellers can include up to 24 pictures in one listing. For inventory items that are a part of an inventory item group/multiple-variation listings, a maximum of 12 pictures may be used per inventory item in the group. Motor vehicle listings are an exception. The number of included pictures in motor vehicle listings depend on the selected vehicle package (see <a href="https://www.ebay.com/help/selling/fees-credits-invoices/motors-fees?id=4127 " target="_blank">Fees for selling vehicles on eBay Motors</a>).<br><br> This container will always be returned for an inventory item gro
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-inventory-item-group-api-openapi.yml