inventory APIv1.6.0

bulkCreateOrReplaceInventoryItem

POST
/bulk_create_or_replace_inventory_item
Note: Please note that any eBay listing created using the Inventory API cannot be revised or relisted using the Trading API calls.

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 bulkCreateOrReplaceInventoryItem call, and then make one or more additional bulkCreateOrReplaceInventoryItem 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.

In the case of updating existing inventory item records, the bulkCreateOrReplaceInventoryItem 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.

The key information that is set with the bulkCreateOrReplaceInventoryItem call include:
  • Seller-defined SKU value for the product. Each seller product, including products within an item inventory group, must have their own SKU value.
  • Condition of the item
  • 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.
  • Quantity of the inventory item that is available for purchase
  • 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.

In addition to the authorization header, which is required for all eBay REST API calls, the bulkCreateOrReplaceInventoryItem 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.

For those who prefer to create or update a single inventory item record, the createOrReplaceInventoryItem method can be used.

Input

Resource URI (production)

POST https://api.ebay.com/sell/inventory/v1/bulk_create_or_replace_inventory_item

URI parameters

HTTP request headers

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

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
requestsarray of InventoryItemWithSkuLocaleThe details of each inventory item that is being created or updated is passed in under this container. Up to 25 inventory item records can be created and/or updated with one bulkCreateOrReplaceInventoryItem call.

Occurrence: Required

requests.availabilityAvailabilityThis container is used to specify the quantity of the inventory item that are available for purchase.

This container is optional up until the seller is ready to publish an offer with the SKU, at which time it becomes required. Availability data must also be passed if an inventory item is being updated and availability data already exists for that inventory item.

Since an inventory item must have specified quantity before being published in an offer, this container is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this container will only be returned if set for the inventory item.

Occurrence: Conditional

requests.availability.pickupAtLocationAvailabilityarray of PickupAtLocationAvailabilityThis container consists of an array of one or more of the merchant's physical store locations where the inventory item is available for In-Store Pickup orders. The merchant's location, the quantity available, and the fulfillment time (how soon the item will be ready for pickup after the order takes place) are all in this container. In-Store Pickup is only available to large merchants selling on the US, UK, Germany, and Australia sites.

Occurrence: Optional

requests.availability.pickupAtLocationAvailability.availabilityTypeAvailabilityTypeEnumThe enumeration value in this field indicates the availability status of the inventory item at the merchant's physical store specified by the pickupAtLocationAvailability.merchantLocationKey field. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.

See AvailabilityTypeEnum for more information about how/when you use each enumeration value.

Occurrence: Conditional

requests.availability.pickupAtLocationAvailability.fulfillmentTimeTimeDurationThis container is used to indicate how soon an In-Store Pickup order will be available for pickup by the buyer after the order takes place. This container is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.

Occurrence: Conditional

requests.availability.pickupAtLocationAvailability.fulfillmentTime.unitTimeDurationUnitEnumThis enumeration value indicates the time unit used to specify the fulfillment time, such as HOUR.

Occurrence: Conditional

requests.availability.pickupAtLocationAvailability.fulfillmentTime.valueintegerThe integer value in this field, along with the time unit in the unit field, will indicate how soon after an In-Store Pickup purchase can the buyer pick up the item at the designated store location. If the value of this field is 4, and the value of the unit field is HOUR, then the fulfillment time for the In-Store Pickup order is four hours, which means that the buyer will be able to pick up the item at the store four hours after the transaction took place.

Occurrence: Conditional

requests.availability.pickupAtLocationAvailability.merchantLocationKeystringThe unique identifier of a merchant's store where the In-Store Pickup inventory item is currently located, or where inventory will be sent to. If the merchant's store is currently awaiting for inventory, the availabilityType value should be SHIP_TO_STORE. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.

Max length: 36

Occurrence: Conditional

requests.availability.pickupAtLocationAvailability.quantityintegerThis integer value indicates the quantity of the inventory item that is available for In-Store Pickup at the store identified by the merchantLocationKey value. The value of quantity should be an integer value greater than 0, unless the inventory item is out of stock. This field is required if the pickupAtLocationAvailability container is used, and is always returned with the pickupAtLocationAvailability container.

Occurrence: Conditional

requests.availability.shipToLocationAvailabilityShipToLocationAvailabilityThis container specifies the quantity of the inventory item that are available for purchase across one or more eBay marketplaces.

Occurrence: Optional

requests.availability.shipToLocationAvailability.quantityintegerThis container is used to set the total 'ship-to-home' quantity of the inventory item that will be available for purchase through one or more published offers. This container is not immediately required, but 'ship-to-home' quantity must be set before an offer of the inventory item can be published.

If an existing inventory item is being updated, and the 'ship-to-home' quantity already exists for the inventory item record, this container should be included again, even if the value is not changing, or the available quantity data will be lost.

Occurrence: Conditional

requests.conditionConditionEnumThis enumeration value indicates the condition of the item. Supported item condition values will vary by eBay site and category. To see which item condition values that a particular eBay category supports, use the getItemConditionPolicies call of the Metadata API, passing in the category ID as a query parameter. The proper syntax to use can be found on the getItemConditionPolicies Call Reference page. The supported item conditions will be returned under the itemConditions container of the getItemConditionPolicies response. The itemConditions container will consist of conditionId and conditionDescription values. The conditionId values must be matched to the enumeration values defined in the ConditionEnum type. See this type document for the mapping information, as one of the values in this type must be specified in the condition field.

This field is optional up until the seller is ready to publish an offer with the SKU, at which time it becomes required.

Since the condition of an inventory item must be specified before being published in an offer, this field is always returned in the 'Get' calls for SKUs that are part of a published offer. If a SKU is not part of a published offer, this container will only be returned if set for the inventory item.

Occurrence: Conditional

requests.conditionDescriptionstringThis string field is used by the seller to more clearly describe the condition of a used inventory item, or an inventory item whose condition value is not NEW, LIKE_NEW, NEW_OTHER, or NEW_WITH_DEFECTS.

The conditionDescription field is available for all eBay categories. If the conditionDescription field is used with an item in one of the new conditions (mentioned in previous paragraph), eBay will simply ignore this field if included, and eBay will return a warning message to the user.

This field should only be used to further clarify the condition of the used item. It should not be used for branding, promotions, shipping, returns, payment or other information unrelated to the condition of the used item. Make sure that the condition value, condition description, listing description, and the item's pictures do not contradict one another.

This field is not always required, but is required if an inventory item is being updated and a condition description already exists for that inventory item.

This field is returned in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls if a condition description was provided for a used inventory item.

Max Length: 1000.

Occurrence: Conditional

requests.packageWeightAndSizePackageWeightAndSizeThis container is used if the seller is offering one or more calculated shipping options for the inventory item, or if the seller is offering flat-rate shipping but is including a shipping surcharge based on the item's weight. This container is used to specify the dimensions and weight of a shipping package.

This container is not always required, but is required if an inventory item is being updated and shipping package data already exists for that inventory item.

This container is returned in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls if package type, package weight, and/or package dimensions are specified for an inventory item.

See the Calculated shipping help page for more information on calculated shipping.

Occurrence: Conditional

requests.packageWeightAndSize.dimensionsDimensionThis container is used to indicate the length, width, and height of the shipping package that will be used to ship the inventory item. The dimensions of a shipping package are needed when calculated shipping is used.

This container will be returned if package dimensions are set for the inventory item.

Occurrence: Conditional

requests.packageWeightAndSize.dimensions.heightnumberThe actual height (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.

If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
"dimensions": {
"length": 21.5,
"width": 15.0,
"height": 12.0,
"unit": "INCH"
}

Occurrence: Conditional

requests.packageWeightAndSize.dimensions.lengthnumberThe actual length (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.

If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
"dimensions": {
"length": 21.5,
"width": 15.0,
"height": 12.0,
"unit": "INCH"
}

Occurrence: Conditional

requests.packageWeightAndSize.dimensions.unitLengthUnitOfMeasureEnumThe unit of measurement used to specify the dimensions of a shipping package. All fields of the dimensions container are required if package dimensions are specified. If the English system of measurement is being used, the applicable values for dimension units are FEET and INCH. If the metric system of measurement is being used, the applicable values for weight units are METER and CENTIMETER. The metric system is used by most countries outside of the US.

Occurrence: Conditional

requests.packageWeightAndSize.dimensions.widthnumberThe actual width (in the measurement unit specified in the unit field) of the shipping package. All fields of the dimensions container are required if package dimensions are specified.

If a shipping package measured 21.5 inches in length, 15.0 inches in width, and 12.0 inches in height, the dimensions container would look as follows:
"dimensions": {
"length": 21.5,
"width": 15.0,
"height": 12.0,
"unit": "INCH"
}

Occurrence: Conditional

requests.packageWeightAndSize.packageTypePackageTypeEnumThis enumeration value indicates the type of shipping package used to ship the inventory item. The supported values for this field can be found in the PackageTypeEnum type.

This field will be returned if the package type is set for the inventory item.

Occurrence: Conditional

requests.packageWeightAndSize.weightWeightThis container is used to specify the weight of the shipping package that will be used to ship the inventory item. The weight of a shipping package are needed when calculated shipping is used, or if flat-rate shipping rates are used, but with a weight surcharge.

This field will be returned if package weight is set for the inventory item.

Occurrence: Conditional

requests.packageWeightAndSize.weight.unitWeightUnitOfMeasureEnumThe unit of measurement used to specify the weight of a shipping package. Both the unit and value fields are required if the weight container is used. If the English system of measurement is being used, the applicable values for weight units are POUND and OUNCE. If the metric system of measurement is being used, the applicable values for weight units are KILOGRAM and GRAM. The metric system is used by most countries outside of the US.

Occurrence: Conditional

requests.packageWeightAndSize.weight.valuenumberThe actual weight (in the measurement unit specified in the unit field) of the shipping package. Both the unit and value fields are required if the weight container is used. If a shipping package weighed 20.5 ounces, the container would look as follows:
"weight": {
"value": 20.5,
"unit": "OUNCE"
}

Occurrence: Conditional

requests.productProductThis container is used to define the product details, such as product title, product description, product identifiers (eBay Product ID, GTIN, or Brand/MPN pair), product aspects/item specifics, and product images. Note that an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) value can be used in an attempt to find a matching product in the eBay Catalog. If a product match is found, the inventory item record will automatically pick up all product details associated with the eBay Catalog product.

Note: For the US, UK, CA (English), and AU sites, eBay is starting to require that some products in certain eBay categories be associated with an eBay Catalog product. For more information on this requirement, see the Product-Based Shopping Experience Playbook topic in the Selling Integration Guide. In an attempt to find a eBay Catalog product match, an ePID value is always preferred over the other product identifiers, since it is possible that one GTIN value can be associated with multiple eBay Catalog products, and if multiple products are found, product details will not be picked up by the Inventory Item object.

Many eBay categories do not require listings to be associated with an eBay Catalog product, but will require at least one product identifier (a GTIN or a Brand/MPN pair). To discover which product identifier(s) that an eBay category requires or supports, use the GetCategoryFeatures call in the Trading API. In the call request, include four FeatureID fields and set the values in those fields to EANEnabled, ISBNEnabled, UPCEnabled, and BrandMPNIdentifierEnabled. In the call response, look for these same field names under the Category node. The values returned in the EANEnabled, ISBNEnabled, UPCEnabled fields will either be Enabled (GTIN type is supported but not required), Required (GTIN type must be supplied for the inventory item), or Disabled (GTIN type is not supported for the category). The BrandMPNIdentifierEnabled is a boolean field, and a true value indicates that the seller must supply brand and mpn values. Ideally, if a GTIN type or Brand/MPN pair is required/supported and is known by the seller, these product identifiers should be supplied for the inventory item. In some cases, a product identifier type may be required, but not known/applicable for a product. If this is the case, the seller must still include the corresponding field in the inventory item record, but pass in a default text string. This text string can vary by site, so the seller should use the GeteBayDetails call of the Trading API to get this string value. In the GeteBayDetails call, the seller should include a DetailName field with its value set to ProductDetails. In the response of the call, the seller can see the default string value in the ProductDetails.ProductIdentifierUnavailableText field. The seller will use this value in one or more of the product identifier fields (ean, isbn, upc, or mpn) if a product ID isn't known or applicable.

This container is not initially required, but it is required before an inventory item can be published as an offer, and/or if an inventory item is being updated and product data already exists for that inventory item.

This container is always returned for published offers in the getInventoryItem, bulkGetInventoryItem, and getInventoryItems calls since product data must be defined for published offers, but for unpublished inventory items, this container will only be returned if product details have been defined for the inventory item.

Occurrence: Conditional

requests.product.aspectsarray of stringThis is an array of item specific pairs that provide more information about the product and might make it easier for buyers to find. To view required/recommended product aspects/item specifics names (and corresponding values) for a specific eBay category, sellers can use the GetCategorySpecifics call of the Trading API. Alternatively, sellers can view similar items on eBay.com in the same category to get an idea of what other sellers are using for product aspects/item specifics.

Sellers also have the option of specifying an eBay Product ID (ePID) or optionally, a Global Trade Item Number (GTIN) through the corresponding fields in the product container in an attempt to find a product match in the eBay Catalog. If a match is found based on the ePID or GTIN value, the product aspects that are defined for the eBay Catalog product will automatically get picked up by the newly created/updated inventory item.

Below is an example of the proper JSON syntax to use when manually inputting item specifics:

"aspects": {
"Brand": ["GoPro"],
"Storage Type": ["Removable"]
}

Note that inventory items that will become part of an inventory item group and multiple-variation listing should have the same attributes that are defined for the inventory item group.

This container will be returned if one or more item specific pairs are defined for the inventory item.

Max Length for Aspect Name: 40

Max Length for Aspect Value: 50

Occurrence: Conditional

requests.product.brandstringThe brand of the product. This field is often paired with the mpn field to identify a specific product by Manufacture Part Number. This field is conditionally required if the eBay category requires a Manufacturer Part Number (MPN) value. If eBay is able to find a product match in the eBay Catalog when an eBay Product ID (ePID) or GTIN value (UPC, ISBN, or EAN) is supplied, all product details of that eBay Catalog product is picked up by the inventory item record (including brand) if the createOrUpdateInventoryItem call is successful.

This field is returned if defined for an inventory item. If a brand was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the brand field.

Max Length: 65

Occurrence: Conditional

requests.product.descriptionstringThe description of the product. The description of an existing inventory item can be added or modified with a createOrReplaceInventoryItem call. The description of an inventory item is automatically populated if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.

Note that this field is optional but recommended. If a listingDescription field is omitted when creating and publishing a single-variation offer, the text in this field will be used instead. If neither the product.description field for the inventory item nor the listingDescription field for the offer exist, the publishOffer call will fail. If the inventory item will be part of an inventory item group/multiple-variation listing, this field should definitely be used to specify how the corresponding product variation is different (e.g. This is the green, extra-large version of the shirt). However, in the case of an inventory item group, the text in the description field of the inventory item group will become the listing description of the actual eBay listing instead of the text in this field.

Basic HTML tags are supported, including the following tags:
  • <b>
  • <strong>
  • <br>
  • <ol>
  • <ul>
  • <li>
  • Table tags including <table>, <tr>, <td>, <th>, <thead>, <tfoot>, <tbody>, <caption>, <colgroup>, and <col>
A seller can not use any active content in their listing description. Active content includes animation or video via JavaScript, Flash, plug-ins, or form actions.

This field is returned if defined for an inventory item. If one of the GTIN types (e.g. UPC) was passed in when the inventory item was created/modified and a product match was found in the eBay catalog, product description is one of the details that gets picked up from the catalog product.

Max Length: 4000

Occurrence: Conditional

requests.product.imageUrlsarray of stringAn array of one or more links to images for the product. 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 an offer can be published, at least one image must exist for the inventory item. Most eBay sites support up to 12 pictures free of charge, and eBay Motors listings can have up to 24 pictures.

A link to a stock image for a product may automatically be populated for an inventory item if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.

This container will always be returned for an inventory item that is part of a published offer since a published offer will always have at least one picture, but this container will only be returned if defined for inventory items that are not a part of a published offer.

Occurrence: Conditional

requests.product.mpnstringThe Manufacturer Part Number (MPN) of a product. This field is paired with the brand field to identify a product. Some eBay categories require MPN values. The GetCategorySpecifics call of the Trading API can be used to see if a category requires an MPN. The MPN value for a product may automatically be populated for an inventory item if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog.

This field is returned if defined for an inventory item. If an MPN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the mpn field.

Max Length: 65

Occurrence: Conditional

requests.product.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. The subtitle of an existing inventory item can added, modified, or removed with a createOrReplaceInventoryItem call.

Note that the same subtitle text should be used for each inventory item that will be part of an inventory item group, and ultimately become one product variation within a multiple-variation listing.

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

Max Length: 55

Occurrence: Optional

requests.product.titlestringThe title of an inventory item can be added or modified with a createOrReplaceInventoryItem call. Although not immediately required, a title will be needed before an offer with the inventory item is published. The title of an inventory item is automatically populated if the seller specifies an eBay Product ID (ePID) or a Global Trade Item Number (GTIN) and eBay is able to find a matching product in the eBay Catalog. If the inventory item will become part of a single-variation offer, and the listing is not a product-based listing, the text in this field will become the actual listing title for the published offer. However, if the inventory item will become part of a multiple-variation offer, the text in title field of the inventory item group entity will actually become the listing title for the published offer instead, although a title can still be provided for the inventory item, and it will actually become the title of the variation.

This field will always be returned for an inventory item that is part of a published offer since a published offer will always have a listing title, but this field will only be returned if defined for inventory items that are not a part of a published offer.

Max Length: 80

Occurrence: Conditional

requests.product.isbnarray of stringThe International Standard Book Number (ISBN) value for the product. Although an ePID value is preferred when trying to find a product match in the eBay Catalog, this field can also be used in an attempt to find a product match in the eBay Catalog. If a product match is found in the eBay Catalog, the inventory item is automatically populated with available product details such as a title, a product description, product aspects (including the specified ISBN value), and a link to any stock image that exists for the catalog product.

This field is returned if defined for an inventory item. If an ISBN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the isbn field.

Occurrence: Optional

requests.product.upcarray of stringThe Universal Product Code (UPC) value for the product. Although an ePID value is preferred when trying to find a product match in the eBay Catalog, this field can also be used in an attempt to find a product match in the eBay Catalog. If a product match is found in the eBay Catalog, the inventory item is automatically populated with available product details such as a title, a product description, product aspects (including the specified UPC value), and a link to any stock image that exists for the catalog product.

This field is returned if defined for an inventory item. If a UPC was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the upc field.

Occurrence: Optional

requests.product.eanarray of stringThe European Article Number/International Article Number (EAN) for the product. Although an ePID value is preferred when trying to find a product match in the eBay Catalog, this field can also be used in an attempt to find a product match in the eBay Catalog. If a product match is found in the eBay Catalog, the inventory item is automatically populated with available product details such as a title, a product description, product aspects (including the specified EAN value), and a link to any stock image that exists for the catalog product.

This field is returned if defined for an inventory item. If an EAN was passed in as an item specific name-value pair through the aspects array in a createOrReplaceInventoryItem call, this value is also picked up by the ean field.

Occurrence: Optional

requests.product.epidstringThe eBay Product Identifier (ePID) for the product. This field can be used to directly identify an eBay Catalog product. Based on its specified ePID value, eBay will search for the product in the eBay Catalog, and if a match is found, the inventory item is automatically populated with available product details such as product title, product description, product aspects, and a link to any stock image that exists for the catalog product.

This field is returned if defined for an inventory item.

Note: For the US, UK, CA (English), and AU sites, eBay is starting to require that some products in certain eBay categories be associated with an eBay Catalog product. For more information on this requirement, see the Product-Based Shopping Experience Playbook topic in the Selling Integration Guide. In an attempt to find a eBay Catalog product match, an ePID value is always preferred over the other product identifiers, since it is possible that one GTIN value can be associated with multiple eBay Catalog products, and if multiple products are found, product details will not be picked up by the Inventory Item object.

Occurrence: Optional

requests.skustringThis is the seller-defined SKU value of the product that will be listed on the eBay site (specified in the marketplaceId field). Only one offer (in unpublished or published state) may exist for each sku/marketplaceId/format combination. This field is required.

Max Length: 50

Occurrence: Conditional

requests.localeLocaleEnumThis field is for future use only.

Occurrence: Optional

Output

HTTP response headers

Output container/fieldTypeDescription
responsesarray of InventoryItemResponseThis is the base container of the bulkCreateOrReplaceInventoryItem response. The results of each attempted inventory item creation/update is captured under this container.

Occurrence: Always

responses.statusCodeintegerThe HTTP status code returned in this field indicates the success or failure of creating or updating the inventory item record for the inventory item indicated in the sku field. See the HTTP status codes table to see which each status code indicates.

Occurrence: Always

responses.errorsarray of ErrorDetailV3This container will be returned if there were one or more errors associated with the creation or update to the inventory item record.

Occurrence: Conditional

responses.errors.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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

responses.errors.messagestringA description of the condition that caused the error or warning.

Occurrence: Conditional

responses.errors.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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

responses.errors.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

responses.errors.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

responses.warningsarray of ErrorDetailV3This container will be returned if there were one or more warnings associated with the creation or update to the inventory item record.

Occurrence: Conditional

responses.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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

responses.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

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

Occurrence: Conditional

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

Occurrence: Conditional

responses.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

responses.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

responses.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

responses.skustringThe seller-defined Stock-Keeping Unit (SKU) of the inventory item. The seller should have a unique SKU value for every product that they sell.

Occurrence: Always

responses.localeLocaleEnumThis field is for future use only.

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
207Multi-Status
400Bad Request
500Internal Server Error

Error codes

CodeDomainCategoryMeaning
25001API_INVENTORYAPPLICATIONAny System error. {additionalInfo}
25002API_INVENTORYREQUESTAny User error. {additionalInfo}
25003API_INVENTORYREQUESTInvalid price. {additionalInfo}
25004API_INVENTORYREQUESTInvalid quantity. {additionalInfo}
25005API_INVENTORYREQUESTInvalid category. {additionalInfo}
25006API_INVENTORYREQUESTInvalid listing option. {additionalInfo}
25007API_INVENTORYREQUESTInvalid Shipping policy information. {additionalInfo}
25008API_INVENTORYREQUESTInvalid Payment policy information. {additionalInfo}
25009API_INVENTORYREQUESTInvalid Return policy information. {additionalInfo}
25011API_INVENTORYREQUESTInvalid tax information. {additionalInfo}
25012API_INVENTORYREQUESTInvalid location. {additionalInfo}
25013API_INVENTORYREQUESTInvalid InventoryItemGroup information. {additionalInfo}
25014API_INVENTORYREQUESTInvalid pictures. {additionalInfo}
25015API_INVENTORYREQUESTInvalid picture URL. {additionalInfo}
25016API_INVENTORYREQUESTInvalid {fieldName}. {additionalInfo}
25017API_INVENTORYREQUESTMissing field {fieldName}. {additionalInfo}
25018API_INVENTORYREQUESTIncomplete account information. {additionalInfo}
25019API_INVENTORYREQUESTCannot revise listing. {additionalInfo}
25020API_INVENTORYREQUESTInvalid package details. {additionalInfo}
25021API_INVENTORYREQUESTInvalid condition information. {additionalInfo}
25022API_INVENTORYREQUESTInvalid attribute. {fieldName}
25023API_INVENTORYREQUESTInvalid compatibility information. {additionalInfo}
25025API_INVENTORYAPPLICATIONConcurrent access of Inventory or InventoryItemGroup. Please try again later
25026API_INVENTORYREQUESTSelling limits exceeded. {additionalInfo}
25501API_INVENTORYREQUESTInvalid picture. {additionalInfo}
25502API_INVENTORYREQUESTInvalid attribute information. {additionalInfo}
25503API_INVENTORYREQUESTInvalid product information. {additionalInfo}
25601API_INVENTORYREQUESTInvalid attribute. {fieldName}
25604API_INVENTORYREQUESTInput error. {additionalInfo}
25701API_INVENTORYREQUESTThese SKU(s) are not in the system
25702API_INVENTORYREQUESTSKU {additionalInfo} is not available in the system
25707API_INVENTORYREQUESTInvalid sku. sku has to be alphanumeric with upto 50 characters in length
25708API_INVENTORYREQUESTInvalid sku
25709API_INVENTORYREQUESTInvalid request. Invalid value for field {additionalInfo}
25713API_INVENTORYREQUESTThis Offer is not available : {additionalInfo}.
25715API_INVENTORYREQUESTInvalid Dimension and Weight
25727API_INVENTORYREQUESTThe number of InventoryItems in the request cannot exceed {additionalInfo}.
25728API_INVENTORYREQUESTInventoryItems should be unique in the request.
25733API_INVENTORYREQUESTValid SKU and locale information are required for all the InventoryItems in the request.

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: Bulk Create Inventory Items

This example will create two inventory items.

Input

This call creates two inventory items. A seller-defined SKU value must be provided for each inventory item. Other details provided for these inventory items include listing title, listing description, item condition, product aspects, URL to item images, and quantity available.
POST
https://api.ebay.com/sell/inventory/v1/bulk_create_or_replace_inventory_item

Output

If an inventory item record is successfully retrieved, a statusCode value of 200 is returned for the SKU. For each SKU, all of the details currently defined for the inventory item record are returned.