Skip to main content

Program news

We hope everyone is well. We want to take this time to share with you some eBay Developers Program updates from the recent quarter (July - September 2024).

Developer Portal improvements

Major enhancements made on the Developer Portal include the following:

  • Streamlined Navigation: Developers can get to information faster with minimal clicks and maximum efficiency, thanks to our improved navigation system.
  • User-Centric Documentation: Under the Develop menu, APIs were grouped more logically into related use cases
  • Interactive Tour Tips: Our new interactive tour tips walk developers through the new navigation.
  • Page-Level Feedback: Feedback is invaluable. With our new feedback system, developers can easily share thoughts on individual documentation pages. Look for the icon on the bottom right of documentation pages.

General Product Safety Regulation update

The General Product Safety Regulation (GPSR) goes into effect on December 13, 2024, and the API endpoints and schema related to providing the necessary details in listings is covered in the API updates section of this newsletter.

See the GPSR Seller Center page for more information about GPSR requirements and answers to frequently asked questions.

Decommission of Economic Operator containers

As announced in the Q2 Newsletter published in July, the EconomicOperator container in the Trading API and the economicOperator container in the Inventory API are deprecated, and will be decommissioned on October 21, 2024. If sellers attempt to use either of these containers after the decommission date, the container and its fields will be silently dropped and will not be added to the new or revised listing.

Developers/sellers will have to use the Manufacturer container and/or the Responsible Persons containers instead. See the Product Manufacturers and Responsible Persons section in API updates for full details.

Rebranding of Promoted Listing campaigns and Item Promotions

eBay marketing-related products have been rebranded, and this is reflected in our API documentation. This rebranding did not affect any of the flows or interface elements in the Sell Marketing API.

Promoted Listings

  • Promoted Listings Advanced is now referred to as Promoted Listings with priority campaign strategy
  • Promoted Listings Standard is now referred to as Promoted Listings with general campaign strategy
  • Offsite Ads is now referred to as Promoted Offsite

Item Promotions are now referred to as Discounts on Seller Hub and eBay help pages.

See the 2024 Summer Seller Update story for more information on changes and enhancements to marketing and promotional tools.

eBay Vault is now PSA Vault

As part of a partnership with Professional Sports Authenticator (PSA), the eBay Vault is now the PSA Vault.

For details and FAQs on the PSA Vault, see the PSA Vault Intro and FAQs. For the latest information on how the PSA Vault works, see the How the PSA Vault works with eBay help page.

Troubleshooting added for top Trading API errors

A new Troubleshooting Steps for Most Common Listing Errors table was added to the Trading API Errors Document. This table is designed to further assist developers who may trigger these errors when using any of the AddItem family of calls in the Trading API.

API updates

The following updates have been made to our APIs this quarter.

Product Manufacturers and Responsible Persons

By December 13, 2024, sellers operating in, or shipping to, EU-based countries, or Northern Ireland, will need to provide contact details for the product manufacturer. The seller will be expected to provide the name and full mailing address for the manufacturer and at least one of the following: email address or contact URL. Note that a contact URL field is not yet available in APIs, but is expected to be added in Q4 2024.

If the product manufacturer is not based in an EU country, or Northern Ireland, the seller must also provide the mailing address and email address or contact URL of at least one Responsible Person who is based in the EU or Northern Ireland.

Trading API schema updates

  • The contact details of the product manufacturer is passed in through the Manufacturer container of the AddItem family of calls, and retrieved (if defined for listing) in the GetItem call.
  • The contact details of a responsible person is passed in through the ResponsiblePerson container of the AddItem family of calls, and retrieved (if defined for listing) in the GetItem call.

Inventory API schema updates

  • The contact details of the product manufacturer are passed in through the manufacturer container of the offer resource methods, and retrieved (if defined for offer) in the GET methods of the offer resource.
  • The contact details of a responsible person is passed in through the responsiblePersons array of the offer resource methods, and retrieved (if defined for offer) in the GET methods in the offer resource.

Metadata API schema updates

The new getRegulatoryPolicies method of the Metadata API can be used to see which leaf categories on an eBay marketplace support, recommend, or require Manufacturer and/or Responsible Persons contact details.

The getRegulatoryPolicies method also indicates which leaf categories on an eBay marketplace support, recommend, or require hazardous material information, product safety information, or energy efficiency labels. See the New getRegulatoryPolicies method section below for more information on using that method.

Product Safety pictograms and statements

As part of GPSR, some leaf categories will start requiring sellers to provide product safety pictograms and statements in their listings. This might include products like toys/games with small pieces that could pose a choking hazard to children.

In the Trading API, the product safety information is passed in through the ProductSafety container of the AddItem family of calls, and retrieved (if defined for listing) in the GetItem call. At least one Pictograms.Pictogram ID and/or at least one Statements.Statement ID must be included when providing ProductSafety details in a listing. The ProductSafety.Component field is fully optional.

In the Inventory API, the product safety information is passed in through the productSafety container of the offer resource methods, and retrieved (if defined for offer) in the GET methods of the offer resource. At least one pictogram ID must be specified in the productSafety.pictograms array and/or at least one statement ID must be specified in the productSafety.statements array. The productSafety.component field is fully optional.

The new getProductSafetyLabels method of the Metadata API returns the alphanumeric IDs for the available pictograms and statements in the pictograms.pictogramId and statements.statementId fields, respectively. These IDs are passed into the Trading API fields and Inventory API arrays mentioned in the two previous paragraphs. The corresponding pictogramDescription and statementDescription fields in the getProductSafetyLabels response have text-based descriptions about each pictograms.pictogramId and statements.statementId, respectively.

The new getRegulatoryPolicies method indicates which leaf categories on an eBay marketplace support, recommend, or require product safety information. See the New getRegulatoryPolicies method section below for more information on using that method.

Adding regulatory documents to listings

Three new methods under the new document resource were added to the Media API to support the upload of regulatory documents to a seller's account. Here's a summary of the three new methods:

  • createDocument: this method stages the document to be uploaded, and if successful, a documentId value is returned in the response and in the Location response header. The documentId value will be needed in both the uploadDocument and getDocument methods. The createDocument request payload requires the type of document and the language(s) used in the document.
  • uploadDocument: this method actually uploads the file to eBay, with the documentId value used as a path parameter. With the initial release of the method, the supported file types are .PDF, .JPEG/.JPG, and .PNG.
  • getDocument: this method returns the current status and metadata of the uploaded document specified through the documentId path parameter. The uploaded document is ready to attach to a listing when a value of ACCEPTED is returned in the documentStatus field in the response.

To add documents to listings In the Trading API, the seller will pass in the DocumentID value through the Documents array in the AddItem family of calls.

To add documents to listings In the Inventory API, the seller will pass in one or more documentId values through the documents array in the offer resource methods.

For the full list of supported documents, see the DocumentTypeEnum type definition.

New getRegulatoryPolicies method

A new getRegulatoryPolicies method was added to the Metadata API to indicate which leaf categories on an eBay marketplace support, recommend, or require the following regulatory details:

  • Manufacturer/Responsible Person contact information
  • Product safety pictograms and statements
  • Hazardous materials pictograms and statements
  • Energy efficiency labels and product information sheets

In the getRegulatoryPolicies response, you will want to look for the value in the supportedAttributes.name field. The value returned in that field will indicate that the information tied to that value (see bulleted list above) is applicable to the corresponding leaf category specified in the categoryId field, and the corresponding usage field will indicate if this information is optional, recommended or required for the leaf category.

The filter query parameter allows you to look for information on 1 to 50 specific leaf categories. If the filter query parameter is not used, metadata on all leaf categories on the specified eBay marketplace is returned.

New GPSR fields returned in Browse API

New GPSR-related schema have been added in the responses in the getItem family of methods in the Browse API. The schema changes are summarized below:

  • If provided by the seller, the manufacturer container will show the contact details for the manufacturer of the product. As part of the GPSR mandate, some leaf categories will start requiring sellers operating in the EU or Northern Ireland to provide the full mailing address for the manufacturer and at least one of the following: email address, phone, or contact URL. Note that a contact URL field is not yet available in APIs, but is expected to be added in future.
  • If provided by the seller, the responsiblePersons container will show the contact details for one or more entities responsible for the product. One or more Responsible Persons will be needed if the product manufacturer provided through the manufacturer container is not based in an EU country or Northern Ireland. The responsiblePersons container should contain the full mailing address for the Responsible Person and at least one of the following: email address, phone, or contact URL. Note that a contact URL field is not yet available in APIs, but is expected to be added in future.
  • If provided by the seller, the productSafetyLabels container will show product safety information for the listing, including one or more pictograms and/or product safety statements in the productSafetyLabels.pictograms and productSafetyLabels.statements arrays.

New seller performance notifications available

Two new seller performance notifications were added to the Notification API.

  • SELLER_STANDARDS_PROFILE_METRICS: this notification is sent to sellers when their Seller Level has changed or is projected to change with the next evaluation cycle. The payload for this notification can be seen in the Async API YAML contract. The payload in that contract is very similar to the getSellerStandardsProfile response payload, so it may be helpful to read the reference docs for that method to fully understand the data that will be returned in notifications.
  • SELLER_CUSTOMER_SERVICE_METRIC_RATING: this notification is sent to sellers to inform them when one or more of their key customer service metrics are trending towards 'very high', and in danger of affecting their Seller Level.The payload for this notification can be seen in the Async API YAML contract. The payload in that contract is very similar to the getCustomerServiceMetric response payload, so it may be helpful to read the reference docs for that method to fully understand the data that will be returned in notifications.

If you are not already integrated with the Notification API, please see the Notification API Overview page for more information on required steps to integrate with the API and subscribe to these and other notification topics.

New suggestMaxCpc method in Sell Marketing API

A new suggestMaxCpc method was added to the Sell Marketing API. With this method, the user will include an array of active item IDs in the request payload, and eBay will return the suggested maximum cost-per-click value if these listings are added to a Promoted Listings smart targeting priority strategy campaign.

The maximum cost-per-click value is specified in the maxCpc.amount.value field in the request payload of createCampaign when the user is setting up a smart targeting priority strategy campaign.

New getExpiredCategories method in Taxonomy API

A new getExpiredCategories method has been added to the Taxonomy API. This method retrieves the mappings of expired leaf categories to their corresponding active leaf categories for the specified eBay marketplace. This the REST API version of the GetCategoryMappings call in the Trading API.

Catalog API enabled for Spain and France

The Catalog API has been enabled for the Spain and France marketplaces. To search on these marketplaces, a user must set the value of the required X-EBAY-C-MARKETPLACE-ID header to EBAY_ES and EBAY_FR, respectively.

eBay deprecation and decommission updates

The following APIs/methods/fields are deprecated, and are scheduled for decommission. Please see the Deprecation Status page for detailed information.

The following APIs/methods/fields have been decommissioned during this quarter:

We hope everyone had a great third quarter, and we are looking forward to working with the community throughout 2024!