Creating a single-SKU listing

Both the Inventory API and the Trading API can be used to create one single-SKU listing. The required steps vary with each of these APIs, so they will be covered individually below. If you’re considering a new integration, eBay recommends using Inventory API.

Creating a single-SKU listing with the Inventory API

A location object , an inventory_item object, and an offer object are all required to publish a listing with the Inventory API. Users have the option of creating an inventory_item object first or a location object first, but both are required before an offer object may be published. A logical flow is defined below:

1. Create the location and location type using the createInventoryLocation method. The seller-defined identifier of the location (merchantLocationKey) is passed in at the end of the createInventoryLocation URI. 
2. Define the item using the createOrReplaceInventoryItem method. The key fields of the inventory_item object are briefly described below:
1. SKU: the seller-defined stock-keeping unit (sku) is passed in as a path parameter.
2. Title and description: the listing title and listing description are passed in under the product container. Optionally, the seller can also define a subtitle.
3. Product aspects: the product.aspects (aka item specifics) of the item are passed in as name-value pairs. 
4. Images: Images: at least one image URL must be passed into the product.imageUrls array. 
5. Listing video: the unique identifier of a listing video can be passed into the product.videoIds array to attach a product video with the listing. 
6. Product identifiers: the product container is also used to provide product identifiers, such as an eBay product ID (epid) or a Global Trade Item Number (GTIN) value. 
7. Item condition: the condition of the item is generally required in most categories. The conditionDescription field is used to provide more information about a non-new item, and the conditionDescriptors array is used to provide applicable information about Graded and Ungraded single trading cards.
8. Product availability: sellers have the option of setting general shipToLocationAvailability.quantity, location-specific availabilityDistributions.quantity, and/or pickupAtLocationAvailability.
3. Define the offer for a sku using the createOffer method. The key fields of the offer  object are briefly described below:
1. SKU: the sku value is needed to specify the product that will be used in the offer.
2. eBay marketplace: the marketplaceId field is needed to indicate which eBay marketplace the offer will get published on. 
3. Format and duration: the listing format can be set to AUCTION or FIXED_PRICE. 
4. Item location: the merchantLocationKey field defines the location of the item. 
5. eBay and store categories: the listing category (aka leaf category) is set in the categoryId field. Optionally, the seller can select a secondaryCategoryId, and eBay store owners can use the storeCategoryNames array to organize the offer into one or two custom store categories.   
6. Prices: the price for a fixed-price listing will be specified in the pricingSummary.price and the starting bid price for an auction listing will be specified in the pricingSummary.auctionStartPrice. If you want to enable an auction listing with the Buy It Now option, you can also include the pricingSummary.price, and prospective buyers can pay this price and get the item before any active bidding begins. Sellers can also set an optional pricingSummary.auctionReservePrice for auction listings. 
7. Available quantity: the available quantity of the item is set through the availableQuantity field, but if this field is omitted the general quantity or location-specific quantity that is set in the inventory item object will be used instead. 
8. Listing description: the listing description is set through the listingDescription field, but if this field is omitted, the text in the product.description field of the inventory item object is used instead.
9. Business policies: the Inventory API requires that business policies are used, so the paymentPolicyId, the returnPolicyId, and the fulfillmentPolicyId fields must be included to specify which payment, return policy, and fulfillment business policies are used for the listing.
10. Regulatory information: use the regulatory container to provide regulatory information as needed, including the product’s manufacturer or  responsiblePersons contact information, hazmat information, productSafety information, energyEfficiencyLabel information, or documents. 
11. Custom policies: use the listingPolicies.productCompliancePolicyIds array, the regionalProductCompliancePolicies.countryPolicies.policyIds array, the regionalTakeBackPolicies.countryPolicies.policyIds array, or the listingPolicies.takeBackPolicyId field to set global or country-specific takeback or product compliance policies.
12. Best Offers: optionally, use the bestOfferTerms container if you would like to accept Best Offers from buyers. 
13. Charitable listings: optionally, use the charity container to donate a percentage of the proceeds for each sale to a registered non-profit organization. 
4. Pass in the unique identifier of an offer through a path parameter in the publishOffer method to publish an offer. Successful publish offer calls will return the listingId for the newly active listing. 

Creating a single-SKU listing with the Trading API

Single-SKU listings can be created with the Trading API using AddItem, AddFixedPriceItem, or  AddItems calls. AddItem supports all listing types. As its name suggests, AddFixedPriceItem only supports fixed price listings. The interface for AddItems is the same as AddItem, but supports up to five new listings being defined in one request payload.

In addition to the three calls mentioned above, there is also a VerifyAddItem call and a VerifyAddFixedPriceItem call that can be used as test calls for AddItem and AddFixedPriceItem, respectively. The payloads, logic, validation checks, and errors/warnings are identical with the VerifyAddItem and VerifyAddFixedPriceItem calls, and the only difference is that the ‘Verify’ versions will not actually publish the listing or incur fees. 

Lots of fields must be defined in a listing, and the process below walks you through in a logical order. Note that AddItem links are used, but the information also applies to AddFixedPriceItem and AddItems.

1. Configure the marketplace-specific information and provide the location of the item. The fields used for this are briefly covered below: 
1. eBay marketplace: specify the eBay marketplace where the listing will be published. This can be done with X-EBAY-API-SITEID HTTP header or with the Site field. Note that the header will require a numeric site ID that maps to the eBay marketplace, but the Site field requires an enumeration value. Both marketplace enumeration values and site IDs can be found in the SiteCodeType definition.
2. Item location: the Country field is required, and then the seller has an option of providing the PostalCode field, or they can provide the city and state through the Location field.
3. Currency: the Currency is also needed, and it should be the standard currency used on the specified eBay marketplace.
4. eBay and store categories: the listing category (aka leaf category) is set in the PrimaryCategory.CategoryID field. Optionally, the seller can select a SecondaryCategory.CategoryID, and eBay store owners can use the Storefront container to organize the listing into one or two custom store categories.   
5. Local listing distance: if the seller is selling a motor vehicle through an eBay Motors Local Market listing, the ListingDetails.LocalListingDistance field can be used to set the radius of the area (in miles) in which the vehicle will be available and exposed to interested local buyers.
2. Configure the details of the item. The key fields are briefly covered below:: 
1. Title and description: define the Title and Description. Optionally, you can include a SubTitle or a SellerProvidedTitle (motor vehicle equivalent of a Subtitle). 
2. Item condition: the condition of the item is generally required in most categories, and the Trading API uses the ConditionID field to set the item’s condition. The ConditionDescription field can be used to provide detailed information about non-new items, and the ConditionDescriptors container must be used to provide applicable information about Graded and Ungraded single trading cards.
3. Product aspects: provide product aspects (aka item specifics) name-value pairs for the item using ItemSpecifics.NameValueList containers.
4. Images: at least one image URL must be provided through the PictureDetails.PictureURL array. 
5. Listing video: the unique identifier of a listing video can be passed into the VideoDetails.VideoID field to associate a product video with the listing. 
6. Product identifiers: the ProductListingDetails container is used to provide product identifiers such as an eBay product ID (ePID) or Global Trade Item Number (GTIN) values. 
3. Configure the offer details and features. The key fields are briefly covered below: 
1. Format and duration: the ListingType field sets the listing format and the ListingDuration field sets the listing duration. 
2. Prices: the price for a fixed-price listing will be specified in the BuyItNowPrice field, and the starting bid price for an auction listing will be specified in the  StartPrice field. If you want to enable an auction listing with the Buy It Now option, you can also include the BuyItNowPrice field, and prospective buyers can pay this price and get the item before any active bidding begins. Sellers can also set an optional ReservePrice for auction listings. 
3. Available quantity: the available quantity of the item is set through the Quantity field. 
4. Business policies: the use of business policies with the Trading API are optional. If the seller’s account is opted in to Business Policies, then the seller must use the SellerProfiles container to specify which payment, return policy, and shipping/fulfillment business policies to use for the listing. If the seller’s account is opted out of Business Policies, listing-level payment, return policy, and shipping fields are used instead of Business Policies.
5. Payment information: if a seller is not using Business Policies, they should include the AutoPay field set to true to receive immediate payment (when applicable) from buyers. One or more PaymentMethods fields will only be needed for listings that support offline payments. 
6. Motor vehicle payment details: For motor vehicle listings requiring a down payment, the seller uses the PaymentDetails container to specify the amount of the down payment, when it’s due, and when the balance of the car sales price is expected from the buyer.
7. Return Policy: if a seller is not using Business Policies, they should include the ReturnPolicy container to provide details of the item’s return policy. Note that not accepting returns is still considered a ‘return policy’, and return policies are needed for most eBay categories.
8. Shipping information: if a seller is not using Business Policies, they will need to provide their shipping information through the ShippingDetails container and other shipping-related fields. Shipping and fulfillment is covered in detail in Step 4.
9. Regulatory information: use the Regulatory container to provide regulatory information as needed, including the product’s Manufacturer or  ResponsiblePerson contact information, Hazmat information, ProductSafety information, EnergyEfficiencyLabel information, or Documents. 
10. Custom policies: use the CustomPolicies container to set global or country-specific takeback or product compliance policies.
11. Best Offers: optionally, include the BestOfferDetails.BestOfferEnabled field and set it to true if you would like to accept Best Offers from buyers. You can also use the ListingDetails.BestOfferAutoAcceptPrice and/or ListingDetails.MinimumBestOfferPrice fields to set price thresholds for automatically accepting or rejecting Best Offers based on the price.
12. Charitable listings: optionally, use the Charity container to donate a percentage of the proceeds for each sale to a registered non-profit organization. 
4. Configure the details of shipping/fulfillment. These fields are required if the seller is not using Business Policies. The key fields are briefly covered below:
1. Handling time: use the DispatchTimeMax field to set the number of business days that the seller commits to shipping out the item after the buyer’s payment clears. Typically values are 0, 1, and 2. If the seller commits to same-day shipping, items must be shipped out that same business day as long as the buyer’s payment cleared before the cutoff time for that business day.
2. Shipping service options: a ShippingServiceOptions container is used for each available domestic shipping service option and an InternationalShippingServiceOption container is used for each available international shipping service option. Up to four domestic and five international shipping service options may be specified. If flat-rate shipping is used and no shipping rate table is being used, the cost for each shipping service is also supplied in these containers.
3. Motor vehicle fulfillment: the BuyerResponsibleForShipping field is used for motor vehicle listings and, in most cases, it is set to true, which means that the buyer is responsible for picking up the vehicle or arranging a third-party freight shipping service.
4. Package handling costs: the ShippingDetails.CalculatedShippingRate container is only used if the seller will be charging the buyer domestic or international package handling charges, and only if the seller is using calculated shipping for domestic and/or international shipping.
5. Ship-to and excluded shipping locations: the ShipToLocations and   ShippingDetails.ExcludeShipToLocation fields are used in tandem to specify where the seller ships to and where the seller does not ship to. For example, a seller may ship to a lot of geographical regions and countries within those regions, but does not ship everywhere. That seller might use a <ShiptoLocations> field and set value to Worldwide, but would then also include <ExcludeShipToLocation> fields and perhaps set values to Africa and Central America and Caribbean. 
6. Shipping Discount Profiles: the InternationalPromotionalShippingDiscount, InternationalShippingDiscountProfileID, PromotionalShippingDiscount, and ShippingDiscountProfileID fields are used to apply shipping discounts to the listing. Shipping discounts are set up under the Marketing tab of Seller Hub or through the SetShippingDiscountProfiles call of Trading API.
7. Shipping rate tables: the RateTableDetails container can be used to apply a domestic and/or international shipping rate table to the listing to control flat-rate shipping costs. See the Using shipping rate tables help topic for more information. 
8. Shipping package details: the ShippingPackageDetails container is used to provide the type, weight, and dimensions of a shipping package. 
9. Shipping business policy cost overrides: the ShippingServiceCostOverrideList container is used if the seller is using business policies, but wants to override the costs of one or more domestic and/or international shipping service options. If the seller is not using business policies, this container is not applicable. 
5. Publish the listing by running the call. A successful call will return the ItemID for the newly active listing and any listing-related fees applied against the listing.

Creating a multiple-SKU listing

A multiple-variation listing (aka multiple-SKU listing) is an eBay listing that contains multiple variations of the same item. For example, a seller might sell the same type of t-shirt in multiple color and size combinations. 

Both the Inventory API and the Trading API can be used to create a multiple-SKU listing. The required steps vary with each of these APIs, so they will be covered individually below.

Creating a multiple-variation listing with the Inventory API

Here are the necessary steps to take in the Inventory API to create a multiple-variation listing: 

1. Use the createOrReplaceInventoryItem or bulkCreateOrReplaceInventoryItem method to create a separate inventory item object for each SKU that will go into the inventory item group object and become variations within the multiple-variation listing. Please adhere to the following when creating each inventory item object:
   

   aspects": {
   	"Color": ["Blue"],
   	"Size": ["Large"]
    }

1. In the product.aspects field, provide only the unique aspect(s) for that particular SKU. The common aspects for the inventory item group will be set in the createOrReplaceInventoryItemGroup method. So, if the SKU was a Large, Blue t-shirt, the aspects field might look like this:
2. You can set the product.title and product.description for inventory item objects, but the equivalent fields in the inventory item group object are what will actually be used in the eBay listing.
3. Ideally, any image provided through the product.imageUrls array should reflect a unique aspect of that particular variation. Often, the provided image will demonstrate the color of that particular variation.
4. An eBay listing can only have a maximum of one product video, so it is recommended that the product.videoIds field of the inventory item object not be used, as it can be set in the inventory item group object instead.

2. Use the createOffer or bulkCreateOffer to create offer objects for each SKU in the inventory item group. Please adhere to the following when creating each offer object:

1. The categoryId value should be the same for all SKUs, since they will be in the same eBay listing. 
2. The format value must be set to FIXED_PRICE for all SKUs. 
3. The listingDuration value must be set to GTC for all SKUs. 
4. The same payment (paymentPolicyId), return (returnPolicyId), and fulfillment (fulfillmentPolicyId) business policies should be used for all SKUs.
5. The pricingSummary.price value can be the same for all SKUs, but it is also allowed for variations in the same listing to have slightly different prices.

3. Use the createOrReplaceInventoryItemGroup method to create and configure the inventory item group object. Please adhere to the following when creating the inventory item group object:
   
   1. The inventory item group object is named by passing in a seller-defined name at the end of the createOrReplaceInventoryItemGroup URI.
   2. Use the variantSKUs array to define each SKU that will belong to the inventory item group and will become a variation within the resultant multiple-variation listing.
   3. Use the aspects field to define all common product aspects for the inventory item group. Remember that the unique or “pivoting” aspects for each variation is actually defined in the inventory item objects.
   4. In the variesBy.specifications array, you will define the “pivoting” aspect(s), and all aspect values that are covered by SKUs within the inventory item group. For example, if the variations varied by color and by size, you would have two  variesBy.specifications.name fields, with one set to “Color” and the other set to “Size”, and then the corresponding variesBy.specifications.values arrays would have all of the available colors and sizes available through SKUs in that inventory item group.
   5. The variesBy.aspectsImageVariesBy field is used if the seller wants to provide images for each SKU that demonstrate how each SKU varies. Commonly, this field’s value is set to “Color”, and then at least one image is provided for each SKU in the inventory item group that demonstrates the color of the SKU.
4. Use the publishOfferByInventoryItemGroup method to publish the multiple-variation listing. If the multiple-SKU listing is successfully published, the listingId for the newly active listing will be returned in the response.

Creating a multiple-variation listing with the Trading API

The AddFixedPriceItem call must be used to create a multiple-variation listing in the Trading API. In addition to following the general guidelines to create a single-SKU fixed price listing in the Trading API, set the AddFixedPriceItem request payload as follows:

1. A Variations.Variation node will be needed for each variation that will be part of the listing. Below are some details on setting up this container:
1. Provide the unique (or pivoting) aspects for each variation through the Variation.VariationSpecifics containers. For example, variations may vary be color and size, so one VariationSpecifics.NameValueList.Name field value would be ‘Color’ and one would be ‘Size’, with the actual ‘Color’ and ‘Size’ values for each variation appearing in the corresponding VariationSpecifics.NameValueList.Value fields. Common product aspects (aka item specifics) for all variations are specified through the ItemSpecifics container.
2. Provide the quantity and price of each variation through the Variation.Quantity and Variation.StartPrice fields. The Item.Quantity and Item.StartPrice fields should NOT be used for multiple-varation listings.
3. Provide the Variation.SKU for each variation. Note that if this field is not used, eBay will automatically generate a SKU value for each variation based on its unique aspects (e.g. ‘Blue, Large’). 
4. Use the VariationProductListingDetails container to provide an eBay product ID (ePID) or a Global Trade Item Number for a SKU 
2. In the Variations.VariationSpecificsSet container, you will define the “pivoting” aspect(s), and all aspect values that are covered by SKUs that will be in the listing. For example, if the variations varied by color and by size, you would have two  VariationSpecificsSet.NameValueList.Name fields, with one set to “Color” and the other set to “Size”, and then the corresponding VariationSpecificsSet.NameValueList.Value fields would have all of the available colors and sizes available through SKUs in the listing.
3. The Variations.Pictures container is used if the seller wants to provide images for each SKU that demonstrate how each SKU varies. Commonly, the Variations.Pictures.VariationSpecificName field’s value is set to ‘Color’, and then the Variations.Pictures.VariationSpecificPictureSet container is used to provide one or more picture URLs that demonstrates each unique color of SKUs in the listing.
4. Run the AddFixedPriceItem call to publish the multiple-variation listing. A successful call will return the ItemID for the newly active listing and any listing-related fees applied against the listing.
   

Creating listings in bulk

Both the Inventory API and the Sell Feed API support bulk listing creation. The required steps vary with each of these APIs, so they will be covered individually below.

Creating listings in bulk with the Inventory API

Here are the necessary steps to take in the Inventory API to create up to 25 listings using three bulk methods:

1. Use the bulkCreateOrReplaceInventoryItem method to define up to 25 inventory item records. The payload for this method is identical to the createOrReplaceInventoryItem method except up to 25 inventory item records can be created instead of just one, and the requests.sku field is specified in the request payload for each inventory item record instead of the sku value being a path parameter like in the createOrReplaceInventoryItem method.
2. Use the bulkCreateOffer method to define up to 25 offers for 25 SKUs. The payload for this method is identical to the createOffer method except up to 25 offers can be created instead of just one, and the requests.sku field is specified in the request payload for each offer instead of the sku value being a path parameter like in the createOffer method.
3. Use the bulkPublishOffer method to publish up to 25 offers for 25 SKUs. The payload for this method is identical to the publishOffer method except up to 25 offers can be published instead of just one, and each requests.offerId value is specified in the request payload for each offer instead of the offer_id value being a path parameter like in the publishOffer method. For each offer that is successfully published, a separate listingId field will be returned in response.
   

   These three Bulk APIs work synchronously and the returned HTTP status code will vary as shown below: 

   • 200 OK: all of the inventory items or offers in the request payload were successfully created, or the offers were successfully published as eBay listings. 
   • 207 Multi-status: some inventory items or offers in the request payload were successfully created, or some offers were successfully published as eBay listings. The statusCode field in the response will indicate which objects failed.
   • 400 Bad Request: this status code indicates that the request fully failed due to invalid or missing data.

Creating listings in bulk with the Sell Feed API

The Sell Feed API lets sellers upload and download various feed files and reports. The two feed types used for bulk listing creation are LMS_ADD_ITEM and LMS_ADD_FIXED_PRICE_ITEM. The size limitation for these feed files is 15 MB, and the files are processed asynchronously by eBay. The status of all upload tasks are tracked with a unique 'task ID'. 

Here are the necessary steps to take in the Sell Feed API to create multiple listings:

1. Stage the task using the createTask method. Use the X-EBAY-C-MARKETPLACE-ID header to set the listing marketplace, and set the feedType value in the request payload to either LMS_ADD_ITEM or LMS_ADD_FIXED_PRICE_ITEM. LMS_ADD_FIXED_PRICE_ITEM must be used if you will be creating multiple-variation listings. If the call is successful, the getTask URI for the task is returned in the Location response header.
2. Use the getTask method to check the status of the task. The value returned in the status field should be CREATED. Proceed to the next step if you see this value.
3. Use the uploadFile method to upload the LMS_ADD_ITEM or LMS_ADD_FIXED_PRICE_ITEM feed file.The same task ID returned in createTask method is used as a path parameter for this method. The uploadFile method does not have a request payload, but you will be uploading an XML data file. See the uploadFile reference documentation and/or the Create the data file topic for more details on how to create and upload the XML file. If the uploadFile call is successful, an HTTP status code of 202 Accepted should be returned. Uploaded files are processed asynchronously, so it may take some time to process the file based on the size of the file.
4. Run another getTask method (using the same task ID) to check status. This time, you will want to see a value of COMPLETED or COMPLETED_WITH_ERROR. COMPLETED is preferable over COMPLETED_WITH_ERROR, as the latter generally indicates that one or more listings were not created successfully. Also check the uploadSummary container. If all listings were successfully uploaded, you should see a value of 0 in the uploadSummary.failureCount field.
5. Use the getResultFile method (using the same task ID as a path parameter) to retrieve the file that indicates the results of the listings creation task. A completely successful task should show item ID values for the newly created listings. For any listings that were not created successfully, you should see an Errors container that may indicate the issue(s) with one or more listings.

Creating listings using eBay catalog products

If creating a listing for a commercial product, it is quite possible that eBay may have this same product defined in their product catalog. If this is the case, the seller can provide an eBay product ID (ePID) or a Global Trade Identifier Number (GTIN) value that can be matched to a specific eBay catalog product, and eBay will prefill the listing using details of that catalog product, including the product’s title, description, aspect name-value pairs, and stock photo. eBay will also put this product into the correct eBay leaf category. 

Both the Inventory API and the Trading API can be used to adopt eBay catalog products to create listings. The required steps vary with each of these APIs, so they will be covered individually below.

Adopting eBay catalog products using the Inventory API

Here are the necessary steps to take in the Inventory API to create a listing based on an eBay catalog product:

1. (Optional, but recommended) Use the search method of the Catalog API if you would like to check first if a matching eBay catalog product exists for your product. This method has a number of filters available, but two common ways to search for a matching product is to provide your product name through the q query parameter, or to provide a UPC, ISBN, or EAN value through the gtin query parameter. It is possible that your search may return multiple eBay catalog products, especially if the q query parameter is used instead of a GTIN value, so you will need to examine the details of the product that is returned under the productSummaries array. If the catalog product seems to be an exact match for your product, proceed to step 2.
2. Use the product container of the createOrReplaceInventoryItem or bulkCreateOrReplaceInventoryItem methods to identify the product using either an epid (best) value, a upc value, an ean value, an isbn value, or a brand/mpn pair. When creating a listing for a new item based on an eBay catalog product, you should not provide any other information under the product container, including the title, description, or aspects, as this data will come from the eBay catalog product. However, if the item is used or if it has been modified at all, you will probably want to add your own photos of the actual item through the imageUrls array, and you may want to modify the description to reflect details of the actual item. 
3. When creating the offer for the inventory item using the createOffer or bulkCreateOffer methods, the includeCatalogProductDetails field must be included and set to true in order for eBay to pre-fill catalog product details for the inventory item and offer objects.
4. Use getInventoryItem and getOffer methods to check the inventory item and offer objects before publishing the offer. Use createOrReplaceInventoryItem to make any adjustments to the inventory item and/or use updateOffer to make any adjustments to the offer.
5. Use publishOffer to publish the listing.

Note: eBay catalog products can also be used for multiple-variation listings, so the same process would be followed above, but you would just need to follow the same steps for each inventory item and each offer object.

Adopting eBay catalog products using the Trading API

Here are the necessary steps to take in the Trading API to create a listing based on an eBay catalog product:

1. (Optional, but recommended) Use the search method of the Catalog API if you would like to check first if a matching eBay catalog product exists for your product. This method has a number of filters available, but two common ways to search for a matching product is to provide your product name through the q query parameter, or to provide a UPC, ISBN, or EAN value through the gtin query parameter. It is possible that your search may return multiple eBay catalog products, especially if the q query parameter is used, so you will need to examine the details of the product that is returned under the productSummaries array. If the catalog product seems to be an exact match for your product, proceed to step 2.
2. Use the ProductListingDetails container of the AddItem and AddFixedPriceItem calls to identify the eBay catalog product using either a ProductReferenceID (ePID) value, a UPC value, an EAN value, an ISBN value, or a BrandMPN pair. When creating a listing for a new item based on an eBay catalog product, you should not provide any of the following information in the Add call, as this information will be picked up from the catalog product:
   
   1. Title
   2. Description
   3. ItemSpecifics

However, if the item is used or if it has been modified at all, you will probably want to add your own photos of the actual item through the PictureDetails container, and you may want to modify the Description to reflect details of the actual item. 

3. Once you publish the listing by running the Add call, you may want to call GetItem to validate that the listing appears as expected.

Creating listing previews for magical listings

The Inventory Mapping API, based on GraphQL, helps sellers create high-quality listings with AI-powered recommendations generated from their existing product data. This API allows sellers and third-party partners to use existing product data to create eBay listing previews, which are then used to create listings through eBay's Listing APIs. The flow diagram below illustrates how to generate listing previews and the subsequent step of creating listings using other eBay APIs.

Important: A listing preview is not a draft or a live listing. It is information generated from external product details that sellers can use to create a listing in a subsequent step. Sellers are expected to review the output of this data before creating listings using other eBay APIs.

Business use cases

The Inventory Mapping API takes minimal seller input and creates listing previews. The following are common use cases for this API.

• New sellers setting up inventory: New sellers can start quickly by providing only a title or an image. This reduces the barrier to entry and helps them build their eBay presence without delays.
• Sellers managing stores or listings on other marketplaces: For multi-channel sellers whose metadata may not match eBay’s structure, the API supports importing inventory using image URLs, titles, seller-defined categories, and custom aspects. This saves time, reduces manual rework, and simplifies migration or synchronization from external systems.
• Sellers offering commodity items: For products with standardized identifiers (for example, ISBNs for books, UPCs for electronics), the API accepts product IDs like GTINs to pull relevant details, validate products, and speed cross-channel listing. This improves listing accuracy and supports catalog-based workflows for high-volume inventory.

Procedure

Steps to create listing previews and listings:

1. Call the startListingPreviewsCreation mutation to use your external product data to generate a preview for each product.
2. Monitor the task status by either:
• Poll the task status
• Subscribe to the Notification API topic LISTING_PREVIEW_CREATION_TASK_STATUS to be notified when the listing previews are ready
3. When the task completes successfully, call the listingPreviewsCreationTaskById query (with the task ID) to retrieve the listing previews.
• The task ID is returned in the StartListingPreviewsCreation mutation response
• The output of the listingPreviewsCreationTaskById query includes listing preview details (category, aspects, ePID if available, AI-suggested title/description, and mappingReferenceId)
4. Review the listing preview and create listings:

   Note: The mappingReferenceId uniquely identifies the recommendation provided by the Inventory Mapping API, and sellers must use it to correlate the listing created and reference it when creating or revising listings.

   • Create Single-SKU listings with the Trading API
   • Create Multiple-variation listings with the Trading API
   • Create Bulk listings with the Sell Feed API