Overview

This guide provides an overview of essential APIs to enhance the eBay marketplace experience for buyers. The Taxonomy API facilitates browsing by retrieving full and partial eBay category trees, suggested leaf categories based on keywords, and item aspects for leaf categories. The Catalog API helps buyers make informed decisions by providing complete and detailed product definitions. The Charity API gives data on charitable organizations linked to eBay for Charity. The GetItemShipping API can be used to estimate the buyer's shipping cost for an item based on the buyer's location and quantity purchased.

API Use Case

Retrieving eBay category information with Taxonomy API

The Taxonomy API can be used to retrieve full and partial category trees. Begin with getDefaultCategoryTreeId to obtain the unique identifier of marketplace categoryTreeId. Use getCategoryTree to access the complete category taxonomy for a marketplace or getCategorySubtree to retrieve a specific category at any level and its descendants.

Improve your search experience by using getCategorySuggestions to find recommendations based on keywords related to product features. This helps buyers find the most suitable categories, making it easier to locate the products they want.

The getItemAspectsForCategory and fetchItemAspects retrieve required, recommended, and optional product aspects. The key difference is that getItemAspectsForCategory targets a single leaf category, while fetchItemAspects downloads a file that covers metadata for all leaf categories. Additionally, the Taxonomy SDK can be used with fetchItemAspects to notify users of any changes to product aspect metadata.

Searching for eBay catalog products
The Catalog API enables buyers to efficiently discover eBay products that align with their desired items, ensuring a seamless shopping experience.

Banner image

To find detailed information about catalog products on eBay, you can use the search method, which allows you to locate multiple items using various filters. You can search for products using category IDs, keywords, aspect filters, GTIN (Global Trade Item Number), and MPN (Manufacturer Part Number). These filters help you find specific products by narrowing down the search criteria.

The search method also includes options for fieldgroups, which let you choose the amount of detail you want in your search results. Additionally, pagination is available to manage large sets of results, letting you decide how many items to display per page and easily navigate through them.

After identifying a product using the search method, you can use the getProduct method to get detailed information about a specific catalog product using its eBay Product ID (ePID).

Retrieving charity information
The Charity API helps buyers find charitable organizations on the eBay for Charity platform that they can support by purchasing items, offering information such as mission statements, registration IDs, and geographical locations.

Banner image

To find information about charitable organizations, you can use the getCharityOrgs method. This method allows you to search for organizations using keywords or registration IDs, providing results that include registration IDs and locations. It also features pagination, which helps you manage large lists of organizations by controlling how many results appear per page and making it easier to navigate through them.

Use the getCharityOrg method to get detailed information about a specific organization. This requires the charityOrgId, which is included in the search results from getCharityOrgs. Using this ID, you can access detailed information about the organization, such as its mission and contact details.

The charity_ids query parameter of Browse API's search method can be used to retrieve items that benefit a specific charity.

Utilizing GetItemShipping to estimate shipping costs

The GetItemShipping API enables users to retrieve shipping cost estimates for items, supporting both flat and calculated shipping services based on the item's location and the buyer's location. This process is essential for helping buyers understand the expenses associated with the shipping services offered in a listing.

The information sent with the API call includes the DestinationPostalCode, which indicates where the shipment is headed, and the ItemID, which specifies the listing involved. These details are essential for providing precise and relevant shipping cost data for both international and domestic destinations.

Code samples

Retrieve a category subtree for the eBay Australia marketplace

curl -X GET "https://api.ebay.com/commerce/taxonomy/v1/category_tree/15/get_category_subtree?category_id=3197"
-H "Authorization:Bearer OAUTH_token"

Retrieve a specific charitable organization

curl -X GET "https://api.ebay.com/commerce/charity/v1/charity_org/302"
-H "Authorization:Bearer OAUTH_token"
-H "X-EBAY-C-MARKETPLACE-ID:EBAY_US"

Error handling

  • Use precise keywords for getCategorySuggestions to match product attributes effectively, avoiding mismatched category selections.
  • Confirm the accuracy of ePID when using getProduct to ensure correct product information retrieval.
  • Validate syntax and accuracy when using search for catalog products to prevent retrieval errors.
  • Double-check registration IDs when using getCharityOrgs.
  • Verify DestinationPostalCode, ItemID, and QuantitySold to prevent inaccuracies in shipping cost retrieval.

Best practices