We hope everyone is well. We want to take this time to share with you some updates that have occurred within the eBay Developers Program over the last quarter (July - September 2023).
eBay Connect 2023
The eBay Connect 2023 virtual conference took place on July 25, 2023. Topics covered in the conference included the following:
- Promoted Listings updates
- Sneakers Authenticity Guarantee updates
- Condition Grading for single trading cards
- eBay International Shipping updates
- New regulatory features
- Buy API updates
For those who did not join the live Webinar, or for those that just want to review the content again, all recordings and all slide decks are available here: https://developer.ebay.com/grow/events/ebay-connect-2023
On September 26, 2023, eBay proudly hosted yet another successful eBay Connect event in Shenzhen, China. This well-organized, full-day, in-person event attracted participation from eBay developers and esteemed partners who joined from across the Greater China region.
Revamped Trading API User Guide published
A revamped Trading API User Guide has been published! The look and feel of the guide has been modernized, and uses the same styles, navigation, and search as other guides on the portal. All topics from the old guide will redirect to the landing page of the new guide.
Upcoming Condition Grading mandates
Beginning on October 23rd, 2023, the item condition for any new trading card listings in the affected categories must be either Graded (Condition ID 2750) or Ungraded (Condition ID 4000), and no other item conditions will be accepted. If not provided after this date, the following operations will fail:
- Trading API calls: AddItem, AddFixedPriceItem, AddItems, VerifyAddItem, and VerifyAddFixedPriceItem
- Inventory API methods: bulkPublishOffer, publishOffer, and publishOfferByInventoryItemGroup
- Sell Feed API upload feed types: LMS_ADD_ITEM, LMS_ADD_FIXED_PRICE_ITEM, LMS_VERIFY_ADD_ITEM, and LMS_VERIFY_ADD_FIXED_PRICE_ITEM
As a reminder, for trading card listings in Non-Sport Trading Card Singles (183050), Collectible Card Games Individual Cards (183454), and Sports Trading Card Singles (261328) categories, the item condition must be set to Graded (Condition ID 2750) or Ungraded (Condition ID 4000). If either of these condition IDs are used, the seller is required to use the ConditionDescriptors container in the Trading API or the conditionDescriptors array in the Inventory API to provide one or more applicable condition descriptor name-value pairs. The getItemConditionPolicies method of the Metadata API must be used to retrieve the numeric identifiers used to provide condition descriptor name-value pairs.
Beginning on January 22, 2024, the item condition for all active trading card listings in the affected categories must be changed to either Graded (Condition ID 2750) or Ungraded (Condition ID 4000). If the affected listings are not revised by the January 22, 2024 deadline, those listings may be at risk of being administratively ended, and the following operations will fail if the item conditions are not updated to Graded or Ungraded:
- Trading API calls: ReviseItem, ReviseFixedPriceItem, RelistItem, RelistFixedPriceItem, and VerifyRelistItem
- Inventory API method: updateOffer
- Sell Feed API upload feed types: LMS_REVISE_ITEM, LMS_REVISE_FIXED_PRICE_ITEM, LMS_RELIST_ITEM, and LMS_RELIST_FIXED_PRICE_ITEM
The following updates have been made to our APIs over the last few months.
Promoted Listing updates in Sell Marketing API
Several Promoted Listing updates were made to the Sell Marketing API, including the following:
- Promoted Listings Advanced (PLA) Quick Setup campaigns now supported. Two new methods, setupQuickCampaign and launchCampaign, were made available to support Quick Setup campaigns. With Quick Setup campaigns, the seller only provides the daily budget and the listings to promote, and eBay will automatically create the ad groups and keywords for the campaign. A successful setupQuickCampaign call will create a PLA campaign in draft mode, and the getCampaign URL for the campaign will be returned in the Location response header. The seller will review this PLA campaign in draft mode using getCampaign, and if everything looks good, the seller will use the launchCampaign method to activate/launch the PLA campaign.
- On the Germany marketplace, Promoted Listings Standard campaigns can now be applied to auction listings.
- Listing format column added to Promoted Listing Reports to distinguish performance of PL campaigns between different listing formats. The new listing format column is now available in the following report types: Campaign Performance report, Inventory Performance report, Listing Performance report, and Transaction report.
eBay Store Email Campaign methods added to Sell Marketing API
8 new methods to support eBay Store Email Campaigns have been added under the email_campaign resource in the Sell Marketing API. There are methods to create, retrieve, update, and delete Store Email Campaigns. Campaign types include Welcome campaigns, New products & collections, Coded Coupons, Sale events & markdowns, Order discounts, and Volume pricing.
Each campaign is directed at one or more audiences/buyer groups. Default audiences include most recent buyers (bought in the last 30 days), recent buyers (bought in the last 31 - 365 days), Store followers (saved you as a seller), and subscribers to social media accounts (if accounts linked to Store). Store sellers can also set up customized buyer groups, although there is currently no API support to create buyer groups.
In addition to the methods to create and manage email campaigns, there are also the following new methods:
- getAudiences: this method retrieves all audiences available to the seller for email campaigns.
- getEmailPreview: this method allows the seller to get a preview of the email before it is sent out.
- getEmailReport: this method retrieves performance metrics for a campaign.
Split-Payout functionality rolled out to China-based sellers
Previously, China-based sellers could only receive payout funds to a Payoneer account, but now they can receive payout funds through a bank account. Sellers can choose to split payout funds to two different accounts at desired percentage rates. For example, sellers could send 50 percent of payout funds to a Payoneer account and 50 percent to a bank account, or they could use an 80/20 split, a 60/40 split or any other split equaling 100 percent, including a 100/0, which means all payouts funds would go to one account, while the other account stays enabled for payouts should the seller want to make changes.
Two new methods were added to Account API v2 to retrieve and update payout settings. The getPayoutSettings method retrieves the seller’s accounts enabled to receive payouts and their current payout percentages. The user will also want to pay attention to the instrumentId in the response of getPayoutSettings, an identifier of the account that will be needed to update the payout percentages through the new updatePayoutPercentage method.
The getPayout, getPayouts, and getTransactions methods of the Finances API were enhanced to support split payouts. Both getPayout and getPayouts will return a new payoutPercentage field to indicate the percentage of payout funds distributed to that account. Additionally, a payoutReference field will be returned in both getPayout and getPayouts to indicate which payouts are associated with a split payout. The payoutReference value can be used as a filter in both getPayouts and getTransactions in order to get data on both sibling payouts associated with that payoutReference identifier. See the V. 1.16.0 Release Notes for more information on interface changes to support split payouts.
Numerous regulatory features live globally
- Global and country-specific Product Compliance policies. Product Compliance policies can be created and managed with the Custom Policy methods in Account API.
- Global and country-specific Takeback policies. Takeback policies can be created and managed with the Custom Policy methods in Account API. The getExtendedProducerResponsibilityPolicies method of the Metadata API indicates which categories on a marketplace support Takeback policies.
- Hazardous Materials information. The getHazardousMaterialsLabels method of the Metadata API retrieves the IDs/enums of the hazardous pictograms, statements, and signal words that will be used in the listing flows to convey hazardous materials information.
- Energy Efficiency Labels and Product Data sheets can now be uploaded for electrical appliances and products. Note: Energy Efficiency Range and Rating item specifics are still needed.
- Repair Score. The getExtendedProducerResponsibilityPolicies method of the Metadata API indicates which categories on a marketplace support repair scores
- Eco-Participation Fee. The getExtendedProducerResponsibilityPolicies method of the Metadata API indicates which categories on a marketplace support eco-participation fees.
Expected API changes for actioned listings
As a part of our continuous work to improve our notice and action programs, eBay will enable changes to the reporting mechanisms on all eBay listings. These changes are expected to go live in the Ireland and France marketplaces on October 16, 2023, live for all other European Union sellers on October 30, 2023, and live in all marketplaces on November 6, 2023.
eBay evaluates and reviews all reports and when eBay decides to take action against a listing, the listing will be hidden. Hidden listings will be hidden from search, and any attempted purchases, offers, or bids will be blocked. Users that have a transactional relationship with the listing will have limited visibility to the hidden listing. In some circumstances, depending on the policy that was violated, eBay will give sellers the opportunity to address the violation and get listings fully reinstated, where possible. Users will be able to appeal listings actions, but there is not an API solution for that yet (planned for early next year). The appeals window default is 6 months, but will require the user to submit via the in-product webform until API solution is available.
Numerous 'GET' operations that retrieve eBay listing data will be updated with warnings and or flags to indicate when a specific listing is hidden, and some item-level data, such as item title and photo URLs will be masked. The table below summarizes the expected updates to our APIs*:
|Schema and/or Behavior Change
For visible on-hold listings
New SellingStatus.ListingOnHold boolean.
For hidden on-hold listings
New error message: "This listing has been removed for a policy violation." with the following URL in ErrorParameters https://www.ebay.com/help/account/regulatory/regulatory-hub?id=5393
Existing Trading error code 17 used: "This item cannot be accessed because the listing has been deleted or you are not the seller."
Existing Trading error code 21917182 used: "OrderLineItemIDs <ORDER_ID> could not be found. Associated Items may have been deleted or removed."
Transactions from hidden listing not returned. No other changes.
Item.Title field returned as '*****************'.
The Item ID value of the listing is displayed in the Item.Title field.
getOffer and getOffers
New listing.listingOnHold boolean.
getOrder and getOrders
The Item ID value of the listing is displayed in the lineItems.title field.
New lineItems.listingOnHold boolean.
Get Inquiry and
New inquiryContentOnHold boolean.
New itemDetails.listingOnHold boolean
itemDetails.itemTitle and itemDetails.itemPictureUrl masked with '*****************'.
Get Return and
New returnContentOnHold boolean.
New itemDetail.listingOnHold boolean
Get Case and
New caseContentOnHold boolean
Note: The initial solution for sellers to view and take action on hidden listings will be a landing page accessible through My eBay and Seller Hub.
New conditionDescriptors column added to Buy Feed Beta API
A conditionDescriptors column was added to getItemFeed and getItemSnapshotFeed. This column will provide Base64 encoded condition descriptor name-value pairs for trading card listings in the Non-Sport Trading Card Singles (183050), CCG Individual Cards (183454), and Sports Trading Card Singles (261328) categories. See the conditionDescriptors field description for more information about the syntax for the returned name-value pairs.
Order v1 API now supports payment of won auctions
Won auction listings can now be added to a checkout session with the initiateCheckoutSession method and paid for using the placeOrder method. An auction listing can only be added to a checkout session if the buyer associated with the user token is the official winning bidder of the auction.
Buy Feed v1 API behavior change
The getFeedType and getFeedTypes methods will no longer return feed types to which the user does not have access. Instead, the user will get a 403 Forbidden status code and a new "Insufficient permissions for the feed type." error.
Custom Policies no longer tied to specific eBay marketplace
Since Product Compliance and Takeback policies are no longer tied to a specific eBay marketplace, the X-EBAY-C-MARKETPLACE-ID HTTP request header is no required or applicable in the createCustomPolicy, updateCustomPolicy, getCustomPolicy, or getCustomPolicies methods of the Account v1 API.
eBay Deprecation and Decommission updates
The following APIs/methods/fields have recently been announced as deprecated. Please see the Deprecation Status page for detailed information.
- The Return Management API is deprecated, with the decommission date yet to be determined. The Post-Order API should be used to manage return requests.
- The GetOrderTransactions call is deprecated and will be decommissioned on January 31, 2024. Developers have the option of migrating to the GetOrders call in the Trading API, or the getOrders method of the Fulfillment API. Please note that the Fulfillment API only returns paid orders, so if your use case calls for retrieving both paid and unpaid orders, we recommend migrating to the GetOrders call in the Trading API.
- Numerous response fields in the GetOrders, GetItemTransactions, GetSellerTransactions, and GetMyeBaySelling calls of the Trading API have been deprecated, and will be decommissioned on January 31, 2024. For the full list of deprecated fields, and the reasons why they are being deprecated, see the Deprecated Trading Order Management Fields document.
- The GetSellerDashboard call of the Trading API is deprecated and will be decommissioned on April 2, 2024. The alternative to this call is the Seller Standards Profile methods of the Seller Analytics API.
- The UpdateReturnPolicy and UpdateSellerInfo fields in the ReviseItem call are deprecated and will be decommissioned on February 26, 2024.
- The CalculatedShippingRate.OriginatingPostalCode field in the Add Item family of calls is deprecated and will be decommissioned on February 26, 2024. This field will also stop being returned by some ‘Get’ calls as well. Please see the Deprecation Status page for full details.
- The ProductListingDetails.TicketListingDetails and Item.QuantityInfo containers in the Add Item family of calls are deprecated and will be decommissioned on February 26, 2024.
- The following four fields in GetMyeBaySelling are deprecated and will be decommissioned on February 6, 2024:
The following APIs/methods/fields were recently decommissioned:
- The GetMyeBayReminders call of the Trading API was decommissioned on July 17, 2023.
- The GetCharities call of the Trading API was decommissioned on September 18, 2023. The alternative to this call is the Charity API.
- The ShippingDetails.CODCost field, used in Add, Revise, Relist, and Get Item calls in the Trading API, was decommissioned on July 17, 2023.
- The PictureDetails.PhotoDisplay field, used in Add, Revise, Relist, and Get Item calls in the Trading API, was decommissioned on July 31, 2023.
We hope everyone had an outstanding summer, and we are looking forward to working with the community during the 2023 holiday season!