eBay Inventory API
The eBay Inventory API allows sellers to manage inventory items, offers, and listing publication on the eBay marketplace.
OpenAPI Specification
openapi: 3.0.0
info:
title: eBay Inventory API
description: The Inventory API is used to create and manage inventory, and then to publish and manage this inventory on an eBay marketplace. There are also methods in this API that will convert eligible, active eBay listings into the Inventory API model.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: 1.17.4
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/inventory/v1
paths:
/bulk_create_or_replace_inventory_item:
post:
tags:
- Inventory_item
description: '<span class="tablenote"><strong>Note:</strong> Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.</span><br><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 can be used to create and/or update up to 25 new inventory item records. It is up to sellers whether they want to create a complete inventory item records right from the start, or sellers can provide only some information with the initial <strong>bulkCreateOrReplaceInventoryItem</strong> call, and then make one or more additional <strong>bulkCreateOrReplaceInventoryItem</strong> calls to complete all required fields for the inventory item records and prepare for publishing. Upon first creating inventory item records, only the SKU values are required.<br><br><span class="tablenote"><b>Note:</b> In addition to the <code>authorization</code> header, which is required for all eBay REST API calls, this call also requires the <code>Content-Language</code> and <code>Content-Type</code> headers. See the <a href="/api-docs/sell/inventory/resources/inventory_item/methods/bulkCreateOrReplaceInventoryItem#h3-request-headers">HTTP request headers</a> section for more information.</span><br> In the case of updating existing inventory item records, the <strong>bulkCreateOrReplaceInventoryItem</strong> call will do a complete replacement of the existing inventory item records, so all fields that are currently defined for the inventory item record are required in that update action, regardless of whether their values changed. So, when replacing/updating an inventory item record, it is advised that the seller run a ''Get'' call to retrieve the full details of the inventory item records and see all of its current values/settings before attempting to update the records. Any changes that are made to inventory item records that are part of one or more active eBay listings, a successful call will automatically update these active listings. <br><br> The key information that is set with the <strong>bulkCreateOrReplaceInventoryItem</strong> call include: <ul> <li>Seller-defined SKU value for the product. Each seller product, including products within an item inventory group, must have their own SKU value. </li> <li>Condition of the item</li> <li>Product details, including any product identifier(s), such as a UPC, ISBN, EAN, or Brand/Manufacturer Part Number pair, a product description, a product title, product/item aspects, and links to images. eBay will use any supplied eBay Product ID (ePID) or a GTIN (UPC, ISBN, or EAN) and attempt to match those identifiers to a product in the eBay Catalog, and if a product match is found, the product details for the inventory item will automatically be populated.</li> <li>Quantity of the inventory item that is available for purchase</li> <li>Package weight and dimensions, which is required if the seller will be offering calculated shipping options. The package weight will also be required if the seller will be providing flat-rate shipping services, but charging a weight surcharge.</li> </ul><p>For those who prefer to create or update a single inventory item record, the <strong>createOrReplaceInventoryItem</strong> method can be used.</p>'
operationId: bulkCreateOrReplaceInventoryItem
parameters:
- 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
- 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
requestBody:
description: Details of the inventories with sku and locale
content:
application/json:
schema:
description: Details of the inventories with sku and locale
$ref: '#/components/schemas/BulkInventoryItem'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BulkInventoryItemResponse'
x-response-codes:
errors:
'25401':
domain: API_INVENTORY
category: APPLICATION
description: Invalid listing options removed. {additionalInfo}
'25402':
domain: API_INVENTORY
category: APPLICATION
description: System warning. {additionalInfo}
'25504':
domain: API_INVENTORY
category: APPLICATION
description: '{additionalInfo}'
'25753':
domain: API_INVENTORY
category: REQUEST
description: listingStartDate is in the past or the offer is live. Value is not updated on the listing.
'207':
description: Multi-Status
'400':
description: Bad Request
x-response-codes:
errors:
'25002':
domain: API_INVENTORY
category: REQUEST
description: Any User error. {additionalInfo}
'25003':
domain: API_INVENTORY
category: REQUEST
description: Invalid price. {additionalInfo}
'25004':
domain: API_INVENTORY
category: REQUEST
description: Invalid quantity. {additionalInfo}
'25005':
domain: API_INVENTORY
category: REQUEST
description: Invalid category. {additionalInfo}
'25006':
domain: API_INVENTORY
category: REQUEST
description: Invalid listing option. {additionalInfo}
'25007':
domain: API_INVENTORY
category: REQUEST
description: Invalid Shipping policy information. {additionalInfo}
'25008':
domain: API_INVENTORY
category: REQUEST
description: Invalid Payment policy information. {additionalInfo}
'25009':
domain: API_INVENTORY
category: REQUEST
description: Invalid Return policy information. {additionalInfo}
'25011':
domain: API_INVENTORY
category: REQUEST
description: Invalid tax information. {additionalInfo}
'25012':
domain: API_INVENTORY
category: REQUEST
description: Invalid location. {additionalInfo}
'25013':
domain: API_INVENTORY
category: REQUEST
description: Invalid InventoryItemGroup information. {additionalInfo}
'25014':
domain: API_INVENTORY
category: REQUEST
description: Invalid pictures. {additionalInfo}
'25015':
domain: API_INVENTORY
category: REQUEST
description: Invalid picture URL. {additionalInfo}
'25016':
domain: API_INVENTORY
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'25017':
domain: API_INVENTORY
category: REQUEST
description: Missing field {fieldName}. {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: Invalid package details. {additionalInfo}
'25021':
domain: API_INVENTORY
category: REQUEST
description: Invalid condition information. {additionalInfo}
'25022':
domain: API_INVENTORY
category: REQUEST
description: Invalid attribute. {fieldName}
'25023':
domain: API_INVENTORY
category: REQUEST
description: Invalid compatibility information. {additionalInfo}
'25026':
domain: API_INVENTORY
category: REQUEST
description: Selling limits exceeded. {additionalInfo}
'25501':
domain: API_INVENTORY
category: REQUEST
description: Invalid picture. {additionalInfo}
'25502':
domain: API_INVENTORY
category: REQUEST
description: Invalid attribute information. {additionalInfo}
'25503':
domain: API_INVENTORY
category: REQUEST
description: Invalid product information. {additionalInfo}
'25601':
domain: API_INVENTORY
category: REQUEST
description: Invalid attribute. {fieldName}
'25604':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25701':
domain: API_INVENTORY
category: REQUEST
description: These SKU(s) are not in the system
'25702':
domain: API_INVENTORY
category: REQUEST
description: SKU {additionalInfo} is not available in the system
'25707':
domain: API_INVENTORY
category: REQUEST
description: Invalid sku. sku has to be alphanumeric with upto 50 characters in length
'25708':
domain: API_INVENTORY
category: REQUEST
description: Invalid sku
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid request. Invalid value for field {additionalInfo}
'25710':
domain: API_INVENTORY
category: REQUEST
description: We didn't find the resource/entity you are requesting. Please verify the request
'25713':
domain: API_INVENTORY
category: REQUEST
description: 'This Offer is not available : {additionalInfo}.'
'25715':
domain: API_INVENTORY
category: REQUEST
description: Invalid Dimension and Weight
'25727':
domain: API_INVENTORY
category: REQUEST
description: The number of InventoryItems in the request cannot exceed {additionalInfo}.
'25728':
domain: API_INVENTORY
category: REQUEST
description: InventoryItems should be unique in the request.
'25733':
domain: API_INVENTORY
category: REQUEST
description: Valid SKU and locale information are required for all the InventoryItems in the request.
'25759':
domain: API_INVENTORY
category: REQUEST
description: shipToLocationAvailability quantity value should be greater than or equal to auction allocation. Please provide valid quantity or unpublish auction offers of the sku.
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: Any System error. {additionalInfo}
'25025':
domain: API_INVENTORY
category: APPLICATION
description: Concurrent access of Inventory or InventoryItemGroup. Please try again later
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
/bulk_get_inventory_item:
post:
tags:
- Inventory_item
description: This call retrieves up to 25 inventory item records. The SKU value of each inventory item record to retrieve is specified 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> header. See the <a href="/api-docs/sell/inventory/resources/inventory_item/methods/bulkGetInventoryItem#h3-request-headers">HTTP request headers</a> for more information.</span><br>For those who prefer to retrieve only one inventory item record by SKU value, the <strong>getInventoryItem</strong> method can be used. To retrieve all inventory item records defined on the seller's account, the <strong>getInventoryItems</strong> method can be used (with pagination control if desired).
operationId: bulkGetInventoryItem
parameters:
- 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 inventories with sku and locale
content:
application/json:
schema:
description: Details of the inventories with sku and locale
$ref: '#/components/schemas/BulkGetInventoryItem'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BulkGetInventoryItemResponse'
'207':
description: Multi-Status
'400':
description: Bad Request
x-response-codes:
errors:
'25702':
domain: API_INVENTORY
category: REQUEST
description: SKU {additionalInfo} is not available in the system
'25708':
domain: API_INVENTORY
category: REQUEST
description: Invalid SKU.
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid request. Invalid value for field {additionalInfo}
'25710':
domain: API_INVENTORY
category: REQUEST
description: We didn't find the resource/entity you are requesting. Please verify the request
'25727':
domain: API_INVENTORY
category: REQUEST
description: The number of InventoryItems in the request cannot exceed {additionalInfo}.
'25734':
domain: API_INVENTORY
category: REQUEST
description: SKU should be unique in the request.
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: Any System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory.readonly
- https://api.ebay.com/oauth/api_scope/sell.inventory
/bulk_update_price_quantity:
post:
tags:
- Inventory_item
description: This call is used by the seller to update the total ship-to-home quantity of one inventory item, and/or to update the price and/or quantity of one or more offers associated with one inventory item. Up to 25 offers associated with an inventory item may be updated with one <strong>bulkUpdatePriceQuantity</strong> call. Only one SKU (one product) can be updated per call.<br><br><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><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> header. See the <a href="/api-docs/sell/inventory/resources/inventory_item/methods/bulkUpdatePriceQuantity#h3-request-headers">HTTP request headers</a> for more information.</span><br>The <strong>getOffers</strong> call can be used to retrieve all offers associated with a SKU. The seller will just pass in the correct SKU value through the <strong>sku</strong> query parameter. To update an offer, the <strong>offerId</strong> value is required, and this value is returned in the <strong>getOffers</strong> call response. It is also useful to know which offers are unpublished and which ones are published. To get this status, look for the <strong>status</strong> value in the <strong>getOffers</strong> call response. Offers in the published state are live eBay listings, and these listings will be revised with a successful <strong>bulkUpdatePriceQuantity</strong> call.<br><br>An issue will occur if duplicate <strong>offerId</strong> values are passed through the same <strong>offers</strong> container, or if one or more of the specified offers are associated with different products/SKUs.<br><br><span class="tablenote"><strong>Note:</strong> For multiple-variation listings, it is recommended that the <strong>bulkUpdatePriceQuantity</strong> call be used to update price and quantity information for each SKU within that multiple-variation listing instead of using <strong>createOrReplaceInventoryItem</strong> calls to update the price and quantity for each SKU. Just remember that only one SKU (one product variation) can be updated per call.</span></p>
operationId: bulkUpdatePriceQuantity
parameters:
- 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: Price and allocation details for the given SKU and Marketplace
content:
application/json:
schema:
description: Price and allocation details for the given SKU and Marketplace
$ref: '#/components/schemas/BulkPriceQuantity'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BulkPriceQuantityResponse'
'207':
description: Multi-Status
'400':
description: Bad Request
x-response-codes:
errors:
'25002':
domain: API_INVENTORY
category: REQUEST
description: Any User error. {additionalInfo}
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid value for {fieldName}. {additionalInfo}
'25759':
domain: API_INVENTORY
category: REQUEST
description: shipToLocationAvailability quantity value should be greater than or equal to auction allocation. Please provide valid quantity or unpublish auction offers of the sku.
'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
/inventory_item/{sku}:
get:
tags:
- Inventory_item
description: This call retrieves the inventory item record for a given SKU. The SKU value is passed in at the end of the call URI. There is no request payload for this call.<br><br>The <code>authorization</code> header is the only required HTTP header for this call, and it is required for all Inventory API calls. See the <strong>HTTP request headers</strong> section for more information.<br><br>For those who prefer to retrieve numerous inventory item records by SKU value with one call (up to 25 at a time), the <strong>bulkGetInventoryItem</strong> method can be used. To retrieve all inventory item records defined on the seller's account, the <strong>getInventoryItems</strong> method can be used (with pagination control if desired).
operationId: getInventoryItem
parameters:
- name: sku
in: path
description: 'This path parameter specifies the seller-defined SKU value of the product whose inventory item record you wish to retrieve.<br><br>Use the <a href="/api-docs/sell/inventory/resources/inventory_item/methods/getInventoryItems" target="_blank ">getInventoryItems</a> method to retrieve SKU values.<br><br><strong>Max length</strong>: 50'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/InventoryItemWithSkuLocaleGroupid'
'400':
description: Bad Request
x-response-codes:
errors:
'25702':
domain: API_INVENTORY
category: REQUEST
description: '{skuValue} could not be found or is not available in the system.'
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid value for {fieldName}
'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
description: '<span class="tablenote"><strong>Note:</strong> Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.</span><br><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 record or replaces an existing inventory item record. It is up to sellers whether they want to create a complete inventory item record right from the start, or sellers can provide only some information with the initial <strong>createOrReplaceInventoryItem</strong> call, and then make one or more additional <strong>createOrReplaceInventoryItem</strong> calls to complete all required fields for the inventory item record and prepare it for publishing. Upon first creating an inventory item record, only the SKU value in the call path is required.<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/methods/createOrReplaceInventoryItem#h3-request-headers">HTTP request headers</a> for more information.</span><br> In the case of replacing an existing inventory item record, the <strong>createOrReplaceInventoryItem</strong> call will do a complete replacement of the existing inventory item record, so all fields that are currently defined for the inventory item record are required in that update action, regardless of whether their values changed. So, when replacing/updating an inventory item record, it is advised that the seller run a <strong>getInventoryItem</strong> call to retrieve the full inventory item record and see all of its current values/settings before attempting to update the record. And if changes are made to an inventory item that is part of one or more active eBay listings, a successful call will automatically update these eBay listings. <br><br> The key information that is set with the <strong>createOrReplaceInventoryItem</strong> call include: <ul> <li>Seller-defined SKU value for the product. Each seller product, including products within an item inventory group, must have their own SKU value. This SKU value is passed in at the end of the call URI</li> <li>Condition of the item</li> <li>Product details, including any product identifier(s), such as a UPC, ISBN, EAN, or Brand/Manufacturer Part Number pair, a product description, a product title, product/item aspects, and links to images. eBay will use any supplied eBay Product ID (ePID) or a GTIN (UPC, ISBN, or EAN) and attempt to match those identifiers to a product in the eBay Catalog, and if a product match is found, the product details for the inventory item will automatically be populated.</li> <li>Quantity of the inventory item that is available for purchase</li> <li>Package weight and dimensions, which is required if the seller will be offering calculated shipping options. The package weight will also be required if the seller will be providing flat-rate shipping services, but charging a weight surcharge.</li> </ul> <p>In addition to the <code>authorization</code> header, which is required for all eBay REST API calls, the <strong>createOrReplaceInventoryItem</strong> call also requires the <code>Content-Language</code> 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 <code>en-US</code>. To view other supported <code>Content-Language</code> values, and to read more about all supported HTTP headers for eBay REST API calls, see the <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank">HTTP request headers</a> topic in the <strong>Using eBay RESTful APIs</strong> document.</p><p>For those who prefer to create
or update numerous inventory item records with one call (up to 25 at a time), the <strong>bulkCreateOrReplaceInventoryItem</strong> method can be used.</p>'
operationId: createOrReplaceInventoryItem
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: sku
in: path
description: 'This path parameter specifies the seller-defined SKU value for the inventory item being created or updated. SKU values must be unique across the seller''s inventory. <br><br> <strong>Max length</strong>: 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 record.
content:
application/json:
schema:
description: Details of the inventory item record.
$ref: '#/components/schemas/InventoryItem'
required: true
responses:
'200':
description: Success
headers:
Content-Language:
schema:
type: string
description: This header controls the language that is used for any returned errors or warnings in the call response.
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}
'25504':
domain: API_INVENTORY
category: APPLICATION
description: "service\t{additionalInfo}"
'25753':
domain: API_INVENTORY
category: REQUEST
description: listingStartDate is in the past or the offer is live. Value is not updated on the listing.
'201':
description: Created
headers:
Content-Language:
schema:
type: string
description: This header controls the language that is used for any returned errors or warnings in the call response.
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}
# --- truncated at 32 KB (479 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-inventory-openapi-original.yml