Trading API
The latest version of the Trading API has rolled out to all the API machines and is now available! Be sure to check out all the new features and known issues.
If you are getting started with the API, the following locations have information about joining the eBay Developers Program, creating test users, and other steps to getting your application certified to go live against the eBay production servers:
|
|
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
These release notes go back four quarters. For older release notes, see the Release Notes archive.
The lowest supported version is 941.
To learn how versioning works in the Trading API, see eBay's Schema Versioning Strategy.
Documentation Changes and Errata - 1177
For a current list of known issues, see Site Status Updates and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
No schema changes in this release.
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1177.
New enumeration values were added to AuthenticityVerificationType. Values now account for order line items that fail authentication and are not able to be returned to the seller because of legal constraints, and for order line items that are passed with exception.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Below is the list of updated error messages that rolled out with the 1177 release:
10122: Picture URL cannot contain semicolon.21920282: New Payment Terms of Use will soon be in effect. Please go to replaceable_value to accept the agreement.21920283: You need to accept the new Payment Terms of Use before you can create or revise listings. Please go to replaceable_value to accept the agreement.These error and warning messages can be viewed in the Errors By Number page.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1177 and Changed Functionality - 1177.
None for this release.
Documentation Changes and Errata - 1173
For a current list of known issues, see Site Status Updates and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
No schema changes in this release.
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
The 2020 Fall Seller Update page was published. Below are some of the highlights:
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1173.
None for this release.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
The currency of the listing fees returned under the Fees container in add/revise/relist calls will reflect the listing site's currency, and not necessarily the seller's default/home currency. Previously, the currency used for these listing fees was the seller's default/home currency even if that seller was listing on a site outside of their home country. This change affects the following calls:
Below is the list of the new error messages that rolled out with the 1173 release:
21920292: You cannot remove a SKU when Item InventoryTrackingMethod is set to SKU.21920293: This application is not permitted to update the eBay fulfillment flag.21920294: Picture URL cannot be a stock photo. replaceable_value picture URL(s) have been dropped.21920295: Picture URL cannot contain html or javascript content like ".cookie", ".location", "ebviewitem.", "showhelp", "showmodaldialog", "navigateandfind", "createpopup", "standardwrite", "writepersonalizedheader", "blockactivecontent".These error and warning messages can be viewed in the Errors By Number page.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1173 and Changed Functionality - 1173.
None for this release.
Documentation Changes and Errata - 1169
For a current list of known issues, see Site Status Updates and the Knowledge Base.
No calls were added, modified, deprecated, or affected by documentation changes in this release.
There are no schema changes in this release.
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
The Quantity and StartPrice response fields in the InventoryStatusType are being deprecated, and they will no longer be supported after April 30, 2022. eBay has found that the values returned for these fields are not reliably accurate and recommends that the responses for these fields be ignored.
The Quantity and StartPrice request fields can still be used, and sellers can leverage the GetItem call to verify that the requested quantity and/or price updates were successful.
This deprecation affects the ReviseInventoryStatus call.
There are no new features in this release.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Error messages (21920285, 21920286, 21920287, 21920288, 21920290, and 21920291) were added to this release of the Trading API. Error message (80) was also updated. Below is the list of the new and updated error messages that rolled out with the 1169 release:
80: This site does not support Private Dutch Auction, Private Buy It Now Auction or Private Fixed Price listings.21920285: Quantity cannot be updated for items that are fulfilled by eBay.21920286: Items that are fulfilled by eBay do not allow these operations - Edit item SKU, Edit variation SKU, Add/Delete variations, Add/Delete variation specifics and Add/Delete variation pictures.21920287: SKU is required in every variation for items that are fulfilled by eBay.21920288: If your item sells for $10,000 or more, you agree to accept payment via Escrow.com and to allow eBay to amend your return policy to offer 7-day returns. Learn more at https://pages.ebay.com/escrow.21920290: eBay fulfillment cannot be applied to an item when there is a pending offer.21920291: Additional shipping cost was dropped from the listing either because it is not applicable or the quantity was set to <=1.These error and warning messages can be viewed in the Errors By Number page.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1169 and Changed Functionality - 1169.
None for this release.
Documentation Changes and Errata - 1165
For a current list of known issues, see Site Status Updates and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
| Name | Part of Schema | Type of Change |
|---|---|---|
AuthenticityVerificationType |
Type | New |
TransactionProgramType |
Type | New |
Transaction.Program |
Field | New |
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
The ReviseSellingManagerSaleRecord call is being deprecated. No new features and/or fields will be added to ReviseSellingManagerSaleRecord, and it will no longer be supported after March 30, 2021. eBay recommends that sellers use the CompleteSale Trading API call to mark orders as paid, mark orders as shipped, and provide shipment tracking details.
The GetCategorySpecifics call is being deprecated. No new features and/or fields will be added to GetCategorySpecifics, and it will no longer be supported after January 31, 2022. eBay recommends that large sellers and developers make plans to migrate to the Taxonomy API RESTful methods.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1165.
A new Program container is returned for orders subject to the Authenticity Guarantee service program. With the Authenticity Guarantee service program, some high-value items in specific categories, like luxury watches or handbags, must be authenticated by a third-party authenticator before being sent to the buyer.
This program is initially only available to a select number of sellers, but this program will eventually become applicable and required for all sellers selling specific items in specific categories.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Error message (21920283) and Warning (21920282) were added as part of the User Agreement Service v2 integration to inform seller about Payments Terms of Use (PTOU). Other messages were also updated. Below is the list of the new and updated error messages that rolled out with the 1165 release:
715: Invalid value provided for Weight Minor. Enter a value between replaceable_value and replaceable_value replaceable_value.21916962: The postage cost will be calculated based on dimensional weight, not the actual weight of your package. Please check the weight and dimensions of your package.21916963: The dimensional weight of your package exceeds the weight limit for the shipping service you selected. Please check the dimensions of your package.21920282: A new User Agreement will soon be in effect. Please go to replaceable_value to accept the agreement.21920283: A new User Agreement is in effect and needs to be signed before you can create or revise listings. Please go to replaceable_value to accept the agreement.These error and warning messages can be viewed in the Errors By Number page.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1165 and Changed Functionality - 1165.
None for this release.
Documentation Changes and Errata - 1161
For a current list of known issues, see Site Status Updates and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
| Name | Part of Schema | Type of Change |
|---|---|---|
RelevanceIndicatorType |
Type | New |
NameRecommendation.RelevanceIndicator |
Field | New |
Item.ListingDesigner |
Field | Removed |
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1161.
A new RelevanceIndicator container is returned in GetCategorySpecifics for item specifics if eBay has data on how many searches have been performed for listings in a specific category using that item specific.
'Buyer Demand Data' is restricted to applications that have been granted permission to access this feature. You must submit an App Check ticket to request this access. In the App Check form, add a note to the Application Title/Summary and/or Application Details fields that you want access to 'Buyer Demand Data' in GetCategorySpecifics.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Platform Notifications will no longer be delivered to non-secure servers/URLs that use the 'http' protocol. Any specified URL must use the 'https' protocol. This means that any URLs specified in the ApplicationDeliveryPreferences.ApplicationURL and DeliveryURLDetails.DeliveryURL fields of the SetNotificationPreferences call must use the 'https' protocol.
The GetNotificationPreferences call may be used to view the current URLs to check if they are using the 'https' protocol.
The calculation of the Final Value Fee is changing for managed payments sellers, so the value returned in the FinalValueFee fields for each order line item in order management call responses should only be considered as estimated values. The getTransactions method of the Finances API can be used to get accurate Final Value Fee values.
See the Selling fees for managed payments sellers help page for more information about how Final Value Fees are changing for managed payments sellers.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1161 and Changed Functionality - 1161.
The retiring of Listing Designer templates was already announced with Version 1157, but now the ListingDesigner field in ItemType has been removed from the 1161 Version of the WSDL. Existing listings that are already using a Listing Designer template will remain unchanged. If a seller tries to use a Listing Designer template using the ListingDesigner container, it will have no effect on the listing, but the seller will receive a warning message about Listing Designer templates no longer being available.
Documentation Changes and Errata - 1157
For a current list of known issues, see Site Status Updates and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
| Name | Part of Schema | Type of Change |
|---|---|---|
DiscountDetailType |
Type | New |
DiscountType |
Type | New |
FeenettingStatusCodeType |
Type | New |
NettedTransactionSummaryType |
Type | New |
GetAccountRequest.IncludeNettedEntries |
Field | New |
GetAccountResponse.FeeNettingStatus |
Field | New |
AccountEntryType.DiscountDetail |
Field | New |
AccountEntryType.Netted |
Field | New |
AccountSummaryType.NettedTransactionSummary |
Field | New |
AccountDetailEntryCodeType.FinalValueFee |
Enum | New |
AccountDetailEntryCodeType.FinalValueFeeCredit |
Enum | New |
AccountDetailEntryCodeType.FinalValueFeeBelowStandard |
Enum | New |
AccountDetailEntryCodeType.FinalValueFeeBelowStandardCredit |
Enum | New |
AccountDetailEntryCodeType.FinalValueFeeFixedFeePerOrder |
Enum | New |
AccountDetailEntryCodeType.FinalValueFeeFixedFeePerOrderCredit |
Enum | New |
AccountDetailEntryCodeType.InternationalFee |
Enum | New |
AccountDetailEntryCodeType.InternationalFeeCredit |
Enum | New |
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
Beginning in June 2020, only the new order ID format will be returned in response payloads for paid orders, regardless of the WSDL version number or compatibility level. When the new order ID format was first introduced in June 2019, eBay gave sellers the option of using the old or the new format. To use the old Order ID format, sellers could use a WSDL older than Version 1113, or they could set the Compatibility-Level header to a value predating Version 1113. That capability is no longer available, and only new order ID values are returned for paid orders. This change affects the following calls:
As part of the Spring 2020 Seller Update, it was announced that new required item specifics were rolled out, or were scheduled to roll out to several categories, including Watches, Electronics, Home & Garden, Business & Industrial, Sporting Goods, Toys, and Fashion. For a complete list of specific changes to these categories, see the Item Specifics page on Seller Center.
Sellers can also use the GetCategorySpecifics call or the getItemAspectsForCategory or fetchItemAspects methods of the Taxonomy API to retrieve the latest item specifics metadata for one, multiple, or all (leaf) categories. A new Taxonomy SDK is also available to compare and discover the item specifics metadata that was recently added or changed in any of eBay's leaf categories.
As of May 31, 2020, sellers are no longer able to use Listing Designer templates when they create or revise listings. Existing listings that are already using a Listing Designer template will remain unchanged.
If a user attempts to use the ListingDesigner container in an Add/Revise/Relist API call, it will have no effect on the listing, but the seller will receive a warning message about Listing Designer templates no longer being available.
The GetDescriptionTemplates call will still retrieve Listing Designer template data, but none of retrieved templates will be usable to create or revise a listing.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1157.
Numerous updates were made to the GetAccount call in preparation for the new features and changes rolling out this summer for eBay managed payments. For sellers enabled for managed payments, some fees will start getting deducted from seller payouts instead of eBay adding those fees to the seller's monthly invoice. These fees include final value fees, a fixed payment processing fee, and an international fee if an order is being shipped internationally.
Because some fees will be charged to a seller right away through a deduction from a seller payout, and other fees will still be billed to the seller's monthly invoice, new capabilities were added to the GetAccount call so a seller can distinguish between which fees have already been paid, and which fees are still due and payable through a monthly invoice.
A quick summary of the changes are below:
true if a managed payments seller wishes to see a breakdown of fees that have already been paid through seller payout deductions.Exempt will be the returned value. true for this container to be returned.true, the amount of the fee (or credit) is a part of the amount shown in the NettedTransactionSummary.TotalNettedChargeAmount or NettedTransactionSummary.TotalNettedChargeAmount fields. If the value is false, the fee (or credit) is being invoiced to the seller. For sellers who are not in managed payments, this fields value will always be false. This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
None for this release.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1157 and Changed Functionality - 1157.
The PrivateListing field was mistakenly removed from the Trading WSDL and docs back in Version 1045, but was added back in Version 1095. Although this field was removed from WSDL, the logic for this field was never wired off and the field was still honored if provided. The PrivateListing field allows sellers to make bidders on auction listings anonymous to other fellow bidders, and only the seller can see bidders' user IDs.
Updated return policy-related documentation to make it more clear that if a seller does not add a separate international return policy for an item, the settings in the domestic return policy will be used instead. For more information on setting separate domestic and international return policies, see the International returns policyhelp topic.
Documentation Changes and Errata - 1149
For a current list of known issues, see Site Status Updates and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
No changed calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
No schema changes in this release.
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
Visit the Spring 2020 Seller Update page for an overview of new and upcoming features and changes that affect sellers.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1149.
None for this release.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Below is a list of the new and updated error messages that rolled out with the 1149 release:
12332: The deposit amount can only be decreased if the item has bid or active Best Offers or is ending in 12 hours. 20002: The length of each Picture URL must be within {0} characters and the total length of all Picture URLs must be within {1} characters.
21917180: Unable to process the charity tags. Please check the seller affiliations/inputs under the Charity Section. 21920270: Item Specific(s) from the product were used instead of these custom Item Specific(s): {0} 21920272: Users with a low feedback rating are not allowed to list an item with Fixed Price format. 21920273: Description cannot be revised for listing that have a bid or have at least one quantity sold or a best offer or ending within twelve hours. 21920274: Failed to add to item description: listing have a bid or have at least one quantity sold or a best offer or ending within twelve hours.
These error messages can be viewed in the Errors By Number page.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1149 and Changed Functionality - 1149.
Some minor doc updates were made to various type files.
Documentation Changes and Errata - 1145
For a current list of known issues, see Site Status Updates and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
No schema changes in this release.
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
Beginning in April 2020, only the new order ID format will be returned in response payloads for paid orders, regardless of the WSDL version number or compatibility level. From June 2019 up until now, users could control whether the new or old order ID format was returned in response payloads. This change affects the following calls:
Note that unique identifiers of orders change as they transition from 'commit to buy'/unpaid to paid orders. So, users will still be able to pass in the IDs for unpaid orders to get the status of those orders, but once orders are paid for, sellers should only use/reference the new order ID format (for paid orders), as these are the identifiers that will also be known to the buyers.
Currently, in Add/Revise/Relist calls, sellers have an option to identify a nonprofit organization with the eBay unique identifier through the Charity.CharityID field, or they can identify the same nonprofit organization using the PayPal Giving Fund unique identifier through the Charity.CharityNumber field. The CharityNumber field has been scheduled for deprecation, so sellers using the CharityNumber field should make plans to migrate to the CharityID field instead.
The eBay unique identifier for nonprofit organizations is shown in the id attribute of each Charity container returned in the response of the GetCharities call.
The ReviseCheckoutStatus call has been staged for deprecation, and this endpoint will no longer be available toward the latter half of 2021. More specific details on exact timing will be announced at a later date. We recommend that you use the CompleteSale call instead of ReviseCheckoutStatus to update the status and/or details of your order. If your use case is to provide shipment tracking information for one or more line items of a paid order, you can use the createShippingFulfillment method of the Fulfillment API to do this task.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1145.
None for this release.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Previously, the Succeeded enumeration value would automatically get returned in the Payment.PaymentStatus field for order payment transactions that were occurring off of eBay's platform. As of March 2020, the Pending value will get returned instead for order payment transactions occurring off of eBay's platform, and the seller can use the CompleteSale call to mark the order as paid. Once the seller does this, the payment status will change from Pending to Succeeded.
This change affects the GetOrders, GetOrderTransactions, GetItemTransactions, and GetSellerTransactions calls.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1145 and Changed Functionality - 1145.
There were several areas in the Call Reference documentation where it wasn't clear if a field was designed for the eBay unique identifier of a nonprofit organization or the PayPal Giving Fund unique identifier of a nonprofit organization. Below is a list of the fields in Trading that identify nonprofit organizations, and whether the values of those fields are for eBay or PayPal Giving Fund charity IDs:
Documentation Changes and Errata - 1139
For a current list of known issues, see Site Status Updates and the Knowledge Base.
These calls were added, modified, deprecated, or affected by documentation changes in this release. The changes are described below as well as in each call's Change History.
No new calls in this release.
Enumeration note: You need to use this release version or higher to retrieve new code list values that were added in this release. See Code Lists.
No schema changes in this release.
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
This section describes new features that have been added as of this release. New features can involve new calls, new capabilities, and/or new fields added to existing calls.
For logical or functional changes to existing features and calls, including code list changes, see Changed Functionality - 1139.
None for this release.
This section describes logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Postal code values returned in the Item.PostalCode field of GetItem will be masked to all users except for the seller of the item. Different countries will mask postal/zip codes in slightly different ways, but an example would be 951**.
The behavior of the fields returned in the FeedbackDetail container of the GetFeedback response has changed in the following ways:
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1139 and Changed Functionality - 1139.
Added a note to the SetPromotionalSale, SetPromotionalSaleListings, and GetPromotionalSaleDetails calls recommending that sellers/developers make plans to migrate to the Marketing API, which provides all Promotions Manager and Promoted Listings capabilities. The Trading API does not support Promoted Listings, and there are no plans for the Trading API to support Promoted Listing or additional Promotions Manager functionality going forward.
Added a note to the VariationProductListingDetails.ProductReferenceID field about it not being supported for any categories. Currently, sellers cannot associate an eBay catalog product with single variations within a multiple-variation listing. If the seller attempts to supply an eBay Product Identifier (ePID) at the variation level, a warning will get returned and the ePID value will just be dropped.
Included a note and a link in the Item.Description field about the View Item Description Summary Feature. This feature allows sellers to customize the description of an item as it appears on a mobile device.
Added site-specific max length values for several address-related fields (in AddressType), including Street1, Street2, CityName, StateOrProvince, and PostalCode. For all five of these fields, the max lengths according eBay marketplace are shown:
For sellers opted in to the feature that supports different same-day handling order cut off times for each business day, the CutoffTime field set in SetUserPreferences and returned in GetUserPreferences is not applicable/usable. This particular field and the DispatchCutoffTimePreference container is designed to only support one order cutoff time.If a seller wishes to view or modify their order cutoff times for same-day handling, that seller must go to Shipping Preferences in My eBay.
Copyright © 2005–2020 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.