Uploading Trading API-related XML data files allow sellers to add, revise, relist, verify, or end listings in bulk. For example, multiple AddItem calls can be contained in one data file. See the XML data files overview for more information on the request file. The request payloads are almost identical to the equivalent calls in the Trading API with a few exceptions:
LMS feed type files must be included in a BulkDataExchangeRequests node (wrapped with opening and closing
One or more items (objects) can be defined in LMS feed type files, unlike the Trading calls that only allow one item at a time
Each object must be contained in an individual node. For example:
Inventory tracking by SKU
When you create a fixed-price listing, you can include a SKU for your own reference. If the SKU is unique across all of your active eBay listings, you can use it as the listing's identifier when you first create the listing. This means you can pass your SKU instead of the item ID in subsequent data file requests, such as ReviseFixedPriceItem, and in several Trading API calls.
Important! To track by SKU, you must make the choice to use SKU when you first create the listing.
When you create a listing, use the InventoryTrackingMethod field to choose whether you prefer to identify the listing by item ID or by SKU. This field defaults to
ItemID, so when tracking by SKU, make sure to explicitly set InventoryTrackingMethod to
SKU, and also provide an Item.SKU (or Variation.SKU for variations). You still can use the item ID as needed.
When you choose to track a listing by SKU, you cannot create and track new listings by the same SKU while the existing listing is active. The Item.SKU value must be unique across all your active listings that have Item.InventoryTrackingMethod set to
SKU does not need to be unique across listings that are tracked by item ID.)
If you need to add more inventory for a given SKU, you can use ReviseInventoryStatus to update the quantity of the existing listing as needed. You can also revise quantity with ReviseItem or ReviseFixedPriceItem.
Note: The eBay website UI cannot identify listings by SKU. For example, My eBay pages and Search pages all identify listings by item ID. When a buyer contacts you via eBay's messaging functionality, eBay uses the item ID as the identifier. Buyer-focused APIs (like the Browse API) also do not support SKU as an identifier.
AddItem, ReviseItem, RelistItem, and VerifyAddItem do not support tracking by SKU or multiple-variation listings. To track by SKU or to use or revise multiple-variation listings, you must use AddFixedPriceItem, ReviseFixedPriceItem, RelistFixedPriceItem, and VerifyAddFixedPriceItem requests.
The first step in this upload flow is to prepare your XML-based data file. Only one type of object can be contained in each file. For instance, multiple AddFixedPriceItem objects can be contained in one data file, but this same file cannot contain ReviseFixedPriceItem objects. As soon as the appropriate upload task is created, this data file will be uploaded using the uploadFile method. For the AddFixedPriceItem object, you would use the feed type of
LMS_ADD_FIXED_PRICE_ITEM with the createTask method. See the Inventory upload feed types for more information.
Note: There are no feed types that support UploadSiteHostedPictures. Use the UploadSiteHostedPictures of the Trading API to upload pictures.
The uploaded and returned files are different types: sellers create and upload data files that contain the seller's requests to eBay; eBay returns the result files after the seller’s upload files are processed. The data file and also eBay's responses returned from a getResultFile method call.
Important! Make sure to use the applicable feed type when creating the task. For example, when creating an AddFixedPriceItemRequest object, call the createTask method using the
LMS_ADD_FIXED_PRICE_ITEM feed type; when creating a ReviseFixedPriceItemRequest object, call the createTask method using the
LMS_REVISE_FIXED_PRICE_ITEM feed type. All create calls in the Trading upload flow use the createTask method of the task resource. Different flows can require different create methods.
Note: You may need to make calls to other APIs to return information for required fields. For example, use the Taxonomy API to determine which category ID is right for your item (getCategorySuggestions, categoryId for <CategoryID>).
Overview of inventory upload flow
There are four basic steps in uploading an Inventory feed type data file to eBay:
Create an upload task.
Use the createTask method to create an upload task. This step returns a taskID in the Location response header (not a response payload field). When creating the upload task, keep the following in mind:
- OAuth tokens are passed in through the Authorization header:
- SchemaVersion is provided through the request payload.
- SiteID values are provided through input Headers in the Feed API.
- The MarketPlaceId value is provided through X-EBAY-C-MARKETPLACE-ID header.
- Sellers can create multiple tasks at a time.
- See Inventory upload feed types for available feed types.
- Create the task using the feed type associated with the data file objects to be uploaded.
- The taskId returned in the create call is used in the uploadfile call.
- Refer to the createTask method for returned errors.
- OAuth tokens are passed in through the Authorization header:
Upload a data file.
Use the uploadFile method to upload a file using the just created taskID. When uploading the file, keep the following in mind:
The data file to upload must be a regular XML file or an XML file in zipped format (both formats are allowed). When uploading the file, use the file's fileName including extension, set name to
file, and type to
After a successful uploadFile method call, eBay starts processing the data file.
Check the task status.
Use the getTask method to retrieve the task's status using the taskID. Use the getTasks method to retrieve details for multiple tasks. When checking the status, keep the following in mind:
- The Feed API does not provide the input file/output file information, but does provide the task's status.
- The Feed API response provides a detail that contains the number of requests successfully processed and failed. It is available under the uploadSummary section in the response. For failed requests, proceed to the next step and download the results file (the file contains any issues or errors).
- Iterate until a response of
- When checking the status of a task, refer to FeedStatusEnum for the possible order status values.
Download the result file.
When the task status is complete, download the result file using taskId and the getResultFile method. Only taskId is required for this operation.
The task can either be completely successful, partially successful (for example, some listings were created and others failed), or the task can completely fail.
For successful tasks, the response includes the ItemID and other information, such as a list of fees associated with the listing. Failed tasks include error messages and codes. If any issues or errors are present, learn about them from the downloaded results file from the getResultFile call. Refer to Troubleshooting and References for Error Messages for information about these errors. Make edits to your request's failed objects, remove any successful objects, and then re-upload.
The following diagram illustrates the calls used when uploading an Inventory feed type data file.
Reusing a data file
Use the Feed API getInputFile method to download a file previously uploaded using uploadFile (useful if you want to revise a group of listings that were previously added or revised).