From inventory item to eBay marketplace offer

The basic flow of using the Inventory API to publish a single-variation offer (create an active listing) involves the use of the following three calls:

1. The createOrReplaceInventoryItem call to create the inventory item record. See inventory_item for required fields.
2. The createOffer call to add details of the listing, including price, eBay marketplace, eBay category, quantity, and listing polices (payment, fulfillment, and return policy). See offer for required fields.
3. The publishOffer call to activate the offer on the eBay marketplace.

The basic flow of using the Inventory API to publish a multiple-variation offer involves the use of the following four calls:

1. The createOrReplaceInventoryItem call to create the inventory item record for each inventory item that will be part of the inventory item group. See inventory_item for required fields.
2. The createOrReplaceInventoryItemGroup call to create the inventory item group and place its members in the group. See inventory_item_group for required fields.
3. The createOffer call to set the listing details for product variation. Since each of the product variations in the inventory item group will be in the same listing, only the SKU, available quantity, and price should vary. Other details such as categoryId, listingDescription, listing policies (payment, return, and fulfillment), merchantLocationKey, and marketplaceId should be the same since these are listing-level settings. See offer for required fields.
4. The publishOfferByInventoryItemGroup call to activate the offer on the eBay marketplace.

Both of the flows above assume that an inventory location has already been set up for the seller. If not, the seller would also have to use the createInventoryLocation call so they could reference an inventory location in the createOffer call.

The diagram below demonstrates the required flow to create an inventory item and convert this inventory item into an eBay offer:

Creating the inventory item record

For each product that a seller intends to sell on an eBay marketplace, an inventory item record is required. Each inventory item record is identified by its seller-defined SKU value. In addition to the required SKU value, the inventory item record also requires the following information:

• Product details
• Quantity available
• Condition of the product
• (Conditional) Shipping package weight and dimensions

Specifying product details

The seller uses the product container of the createOrReplaceInventoryItem call to provide product details such as title, subtitle, description, product aspects, and links to images. Images can be self-hosted by the seller (the site hosting the image file(s) must support 'https' protocol for offer to be successful), or the seller 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, and this URL will be passed in through the product container.

If the eBay category requires one or more product identifier types such as an EAN, an ISBN, a UPC, or a Brand/Manufacturer Part Number pair, the seller must provider these identifier values under the product container. A seller can determine which eBay categories support/require which product identifier types by using the GetCategoryFeatures call of the Trading API. More information on how to use this API call to do that can be found in the createOrReplaceInventoryItem Call Reference page.

If the product is matched to a product in the eBay Catalog, eBay will auto-populate the product details for the inventory item record, and this includes the product title, product description, item specifics, and a link to any stock images. If the eBay category requires a product identifier type but the identifier is not known for the product, the seller must pass a text string into the product identifier type field. The text string to pass in can vary by site, and this text string can be found by using the GeteBayDetails call of the Trading API. More information on how to use this API call to do that can be found in the createOrReplaceInventoryItem Call Reference page.

If a product match is found in the eBay catalog, and the product details are auto-populated, it is recommended that the seller should use a getInventoryItem call to make sure that the product details for the inventory item record are acceptable before creating an offer. If changes are needed, the seller will have to use an additional createOrReplaceInventoryItem call to make any necessary changes to product details.

The product.title and product.description values that are given for the inventory item will become the listing title and listing description for the live eBay listing. For inventory items that will become product variations within the same multiple-variation listing, these fields must have the same values since each of these variations will be a part of the same eBay listing. Similarly, if used, the product.subtitle values for those inventory items in the same inventory item group must also be the same.

Specifying quantity

The seller uses the availability container of the createOrReplaceInventoryItem call to specify the quantity of product that is available through the traditional ship-to-home method, In-Store Pickup (only available in US).

For the traditional ship-to-home method, the seller uses the availability.shipToLocationAvailability container to specify the quantity available. The locations where the seller is willing to ship to will be contained in the fulfillment listing policy that will be referenced when the seller creates the offer. Fulfillment, payment, and return listing policies are created and managed with the Account API. For In-Store Pickup, the seller uses the availability.pickupAtLocationAvailability container to specify the quantity available and fulfillment time at one or more physical stores. See In-Store Pickup for additional details.

Specifying condition of product

A supported item condition enumeration value must be passed in through the condition field of createOrReplaceInventoryItem call to specify the condition of the product. If the product is used or refurbished, it is also a good idea if the seller uses the optional conditionDescription field to more clearly describe the condition of the inventory item. The conditionDescription field is not applicable to inventory items in new condition, and this field will be ignored if it is passed in for a inventory item in new condition. Item condition values can vary by eBay category, so the seller should use the GetCategoryFeatures call of the Trading API to retrieve the supported condition values. More information on how to use this API call to do that can be found in the createOrReplaceInventoryItem Call Reference page.

Specifying package weight and dimensions for calculated shipping

The shipping package weight and dimensions will be needed if the seller will use calculated shipping. The package weight and dimensions will be set using the packageWeightAndSize container of the createOrReplaceInventoryItem call. Package weight will also be needed if the seller is using flat-rate shipping but is charging a weight surcharge for shipping the item.

Creating the offer

Once an inventory item record has been created for a product, the seller can then create an offer for that product on a specific eBay marketplace. Details of the product have already been established with the inventory item record, but the createOffer call will add the following listing details:

• The eBay marketplace where the product will be offered
• The available quantity of that product on that eBay marketplace
• The listing format
• The eBay category where the product will be listed (to determine the category, see Finding categories for a listing or promotion)
• Referenced Payment, Fulfillment, and Return listing policies that set payment, fulfillment, and return-related values and settings in the Offer
• The price of the product, and if applicable, the Minimum Advertised Price and Strikethrough Price information
• Full paths to one or two eBay Store categories for sellers who own an eBay Store on that eBay marketplace and wish to upload the product to one or two eBay Store categories;
• Any tax-related information including the use of tax tables, VAT percentages, or third-party tax category exception codes

Note that Payment, Fulfillment, and Return listing policies are all required when creating an offer. The seller must be opted in to Business Policies. Business policies are created and managed with the Account API, or in the Business Policies page of My eBay.

For inventory items that will become product variations within the same multiple-variation listing, some fields must have the same values since each of these variations will be a part of the same eBay listing. These fields include the following:

• categoryId
• listingDescription
• listing policies - paymentPolicyId, returnPolicyId, fulfillmentPolicyId
• merchantLocationKey (inventory location)
• tax settings
• eBay store categories
• marketplaceId
• format

Upon successful creation of the offer, a unique offerId value will be returned. This offerId value will be required for other offer calls, including updateOffer, publishOffer, deleteOffer, and getOffer. See the createOffer Call Reference page for more information on creating the request payload and executing the API call.

Publishing the offer

Once an offer is created, and the seller is happy with it, it is time to publish the offer with the publishOffer call. With this call, the seller only needs to pass in the offerId value at the end of the call URI. The offer's offerId value is returned in the response of a createOffer call. A successful publishOffer call will actually create an eBay listing on the marketplace that was specified with the createOffer call that created the offer.

Upon successful publishing of the offer, an eBay listing ID is returned in the publishOffer response. If the publishOffer call fails, the reason for the failure will be returned under a errors container in the call response and/or through an HTTP status code page.

The publishOfferByInventoryItemGroup call is used to convert all unpublished offers associated with an inventory item group into an active, multiple-variation listing.

The unique identifier of the inventory item group (inventoryItemGroupKey) is passed in the request payload. All offers in the inventory item group must be valid (meet all requirements) for the publishOfferByInventoryItemGroup call to be successful. A new listing will not be created with the publishOfferByInventoryItemGroup call if one or more offers in the inventory item group have issues. Be sure to check for any error or warning messages in the call response for any applicable information about one or more offers having issues.