Skip to main content
Published: April 22 2015, 3:01:00 PMUpdated: November 28 2020, 8:11:42 PM


When sending addItem (or any) API calls, how is it determined which store/seller the listing is related to? I see there are 3 keys & 1 token...but I'm not sure if that's related directly to a seller?

The token uniquely identifies the eBay seller and their store. The keys identify the application.

When I run getCategories call, I get <Version>659</Version> in the response.
Is that just a coincidence that the version number matches the current compatability level? I was told that this <Version> field can help me determine if the categories have changed since the day before...but if it's just the compatability level in that field, then does it still help me?

<Version> refers to the API version. This field will always come back with the latest version of the eBay API, regardless of the compatibility level you specified. The compatibility level you specify will indicate to the server to process/validate your request based on that version of the schema.

You should be checking the CategoryVersion tag which indicates the version of the category hierarchy on the site. For detailed info read this.

When should we use "Bulk Data Exchange" -- for how many API calls?

BDX or LMS as we call it is an asynchronous mechanism to list and manage your inventory on eBay. This was specifically designed for large merchants like you who want to upload and manage a lot of inventory on the site. If you need to make frequent and instantaneous updates to products, the Trading API would suit you better.

How delayed is the BDX? Is it just the time it takes to send all the addItem requests? Or, is there additional processing time? If my program sends the request, will it receive a response immediately after sending the whole request? If not, how/when does the response come?

The delay will be the time required to parse your input payload file, execute the individual requests and put together a response file. So it will depend on how heavy your input payload file is. In case of reports it will depend on the time required to put together your report (so in the case of SoldReport - it will depend on how heavy the report is i.e. # of sales transactions that you have)


I set the ListingDuration tag to GTC, but the listing looks like it's up for 30 days, not GTC. Is that how the listing will look, but the item will automatically relist after that time, without my doing anything?

Yes. Perfect understanding. FYI The ItemID remains the same when a GTC item is renewed at the end of the 30 day period.

One of the ways of getting your listing to 'surface' when searched is Listing with a Product ID if the item is in the eBay Catalogs – this will ensure that your item will surface categories that display products and items together (Product Display Pages). Which "Product ID" is this referring to? ePID? or something else?

Thats right. That is the advantage of listing with ProductDetails. It could be anything MPN, UPC, EAN or ePID.

What's the difference between using AttributeSetArray vs.ItemSpecifics vs. LookupAttributeArray in AddFixedPriceItem?

They are different models of associating item specifics (name-value Vs ID based) with listings. Some eBay categories (for e.g. clothing, shoes) have been migrated to the newer name-value item specifics model. So when listing items in those categories specify item specifics as name value pairs. For non-migrated categories you will need to use the ID based attributes. The LookupAttributeArray container allows you to specify condition as name value pairs. LookupAttributeArray is intended to be used as a shortcut for specifying the Condition attribute by name instead of by ID. It is only valid when listing items in categories that support product details (catalog-enabled categories). You would still need to look up the string literals associated with the condition using the GetAttributeCS call.

You may find this KB article that talks about the item specifics changes helpful.

I'm confused with the returned fees. Is the <Fee> with the <Name> of "ListingFee"-- is that the total fee (includes insertion, subtitle charges, other enhancements, etc)?? And the <PromotionalDiscount> means I should add the discount amount or subtract it?

The total cost of all listing features is returned in the Fee container whose Name value is ListingFee. If this container has a PromotionalDiscount field, the PromotionalDiscount value is the total of all the promotional discounts that were applied when the item was listed, and the Fee value is the total cost of all listing features minus the promotional discounts. In addition the response will contain multiple fee containers. Each Fee container has both a Name and a Fee element, representing the name and cost of an eBay listing feature. Note that eBay returns Fee containers for all available listing features, even if their cost is zero. When a discount has been applied, the Fee value represents the post-discounted cost for the particular listing feature. To determine what the fee would have been without the discount, add together the values of Fee and PromotionalDiscount. For full details visit -

In short - Non-discounted fee = fee charged + discount.

When a discount has been applied, the Fee value represents the post-discounted cost for the particular listing feature. To determine what the fee would have been without the discount, add together the values of Fee and PromotionalDiscount.


Why is the response of my GetCategory2CS call so short? Even when I run it without the <CategoryID> field (which I think means I should be getting all category data). It seems like it's returning ONE AttributeSetID and that's all. Is it the same AttributeSetID for ALL categories? I should now call getAttributeCS with this AttributeSetID as the parameter?

I get:

 <?xml version="1.0" encoding="UTF-8"?>
<GetCategory2CSResponse xmlns="urn:ebay:apis:eBLBaseComponents">

My request was:

 <?xml version="1.0" encoding="utf-8"?>
<GetCategory2CSRequest xmlns="urn:ebay:apis:eBLBaseComponents">
<eBayAuthToken>TOKEN HERE</eBayAuthToken>

That's because DetailLevel was not specified in your request. When this happens, the response returns the attribute system version (with no mappings). Use this level when you only want to check whether to refresh your locally stored attribute meta-data. If the version hasn't changed, you don't need to refresh your local meta-data.

Do I need to know the eBay categories?

Yes. You will need to do a category mapping exercise to map your product categories with eBay leaf categories.
Answer Title: Best Practices for GetCategories API call
Answer Link:

How to I know whether I should list with ID based attributes or custom item specifics?

Yes you will need to map the item specifics or ID based attributes beforehand and then simply use those when you list items. First you need to identify if the category you are interested in support ItemSpecifics or are still on the ID based model. The following sample shows how to find which leaf categories are enabled to use ItemSpecifics. If the response contains ItemSpecificsEnabled as Enabled for a category, it means that the category supports the newer item specifics.

<?xml version="1.0" encoding="utf-8"?>
 <GetCategoryFeaturesRequest xmlns="urn:ebay:apis:eBLBaseComponents">

The following sample requests item specifics information for all categories. The response will return a FileReferenceID and TaskReferenceID, which identify a particular file that contains recommendations for the specified site.
Once every day or two, call GetCategorySpecifics again to see if the FileReferenceID and TaskReferenceID have changed. If they have changed, use the new IDs to download the latest version of the file.

<?xml version="1.0" encoding="utf-8"?>
<GetCategorySpecificsRequest xmlns="urn:ebay:apis:eBLBaseComponents">

If a category is not ItemSpecificsEnabled, you will need to use the older ID based attributes. In that situation make a call to GetCategory2CS and get the value of the AttributeSetID. Use this when you make a call to GetAttributeCS to get a list of all the attributes applicable for that category. I would think checking the ID based attributes once every day or two would be a good idea as well.

Can I determine all the categories that are ItemSpecificsEnabled?

Yes indirectly. The GetCategoriesSpecifics response (zip file) has item specifics for all the eBay leaf categories that are ItemSpecificsEnabled. You can look at the file to derive what all categories support the newer model. For details on how to download item specifics all at once refer the following section - "Downloading Recommendations for All Categories at Once" at the link below -


How can I find a ShippingService that ships in"x' days?

The following sample shows how to retrieve ShippingServiceDetails for the specified site. Look at the ShippingTimeMax and ShippingTimeMin fields.

<?xml version="1.0" encoding="utf-8"?>
<GeteBayDetailsRequest xmlns="urn:ebay:apis:eBLBaseComponents">


I'm getting a warning (not error): "You did not provide a value for additional shipping cost. The same value you provided for shipping cost has been copied to the additional shipping cost field." I don't really know what this means.

You listed a multi-quantity item and did not provide a value for the shipping service cost for additional items. So lets say you listed an item (qty 5) with ShippingServiceCost = 2.5. If a buyer purchases 2 items, then how would you want him to be charged for shipping? In this case per the warning the buyer will be charged 2.5 + 2.5. If you want additional items to have discounted shipping, then you want to specify the value in the ShippingServiceAdditionalCost field.

You may also want to look at Promotional Shipping -

I'd like to specify in my addFixedPriceItem call that I'm only shipping (for right now) to domestic locations. Do I need to specify every other international country in ExcludeShipToLocation tags? I'm assuming not...but, is it enough to just leave out an <InternationalShippingServiceOption> tag?

If you leave out the InternationalShippingServiceOptions container, your item will appear as "Ships to: United States"

Can you please point us towards the correct API calls to use in order to turn on the “Add a surcharge for Alaska, Hawaii, and Puerto Rico” option on our listings and to set the surcharge value?

To add Shipping Surcharge to your listing you can pass the following tag in the AddFixedPriceItem request

To add surcharge for existing items you will need to send the surcharge value in the ReviseFixedPriceItem call. Please make sure that you send the entire Shipping Details container when you revise the item.

Turning off shipping to non-continental US. It seems we are unable to restrict shipping to HI/AL and other non-continental states?
As of now there isn’t a way to block purchases from buyers from specific states within a country. Therefore we recommend that the shipping restrictions be clearly mentioned in the item description. If you do get an order from a buyer from one of those states, you can talk to the buyer to cancel the sale and refund the money.

It seems ebay does not allow shippng fee>$4 on certain categories. is it a sandbox issue or is it some policy that we do not know about?
For some categories, eBay imposes a maximum on the shipping cost that a seller can specify for the first domestic flat rate shipping service.
Please follow the link below to understand how to get past the error -


How does setting Item.Storefront and Item.Storefront.StoreCategoryID change the way the listing will appear?

All of your items appear in your eBay Store, irrespective of their selling format. Creating store categories and including them in your request under the Storefront container helps you organize items within your store.
Items can only be contained within child store categories. Stores support three levels of categories. Use SetStoreCategories to create or modify the category structure of your store. Multiple categories can be added to a store in a single call but they all should be at the same level. You may also set up your store categories via the website (My eBay - > Manage Store -> Store Categories). Use GetStore to retrieve the category structure for your store.


We'd like to know if there is any API that allows us to send transactions to be cancelled. similar to fulfillment update.
can we use the same API? set status='cancel'?

No API available to cancel orders. Orders once created stay in the system for 120 days and then drop off.



We need to do partial refunds on some items that were funded via eBay bucks. But we get an error everytime we try to issue one via the PayPal API. "You can not do a partial refund on this transaction"
Partial refunds cannot be issued on transactions that used coupons/eBay bucks.


Does it cost to open a Store in Sandbox? Can I possibly import my existing store into the Sandbox?

The Sandbox and production are completely separate environments and data cannot be exchanged between the two. So you will need to create a test store in Sandbox for the sandbox user you have created. You won't be charged for anything in Sandbox.

Can you create a Store for me in Sandbox?

You can create your own store. But first I will need to link your sandbox user account with your paypal seller account (the business test account address to link (it will be %_biz@..)). Can you provide me with the same?

If you haven't created the PayPal test accounts, refer this KB below for steps -

I have linked your accounts. You can now go ahead and create your store

1. Click the Open an eBay Store link in the upper right-hand corner of
2. Sign in and follow the instructions to create a Sandbox Store for the user.

I'm not sure why my listings only have an "inside" image, that you see when you are on the listing itself...but on the search page that shows all matching results, my items have no image. Obviously, there's a field I'm missing that indicates this...but I'm not sure which?

The image that appears on the search results page is what we call the Gallery Image. The Sandbox doesn't support the Gallery Image feature.

Answer Title: Unsupported features list for the Sandbox
Answer Link:

You should be fine as long as you have included these in your request

# The GalleryType is not None
# The GalleryURL is correct

Please review the following section of the documentation on best practices about getting and maintaining the attribute data


How well did this answer your question?
Answers others found helpful