Merchant Data API
You can find links to the Merchant Data API documentation in the top navigation bar.
Are you new to the Large Merchant Services solution?
If so, see Large Merchant Services User Guide -- an introduction to the eBay Large Merchant Services solution.
Are you just getting started with the eBay Developer's Program?
The following links provide useful information for beginners:
|
|
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
These release notes go back four quarters. For older release notes, see the Release Notes archive.
Documentation Changes and Errata - 1131
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 |
|---|---|---|
OrderDetailsType.TotalIncludeseBayCollectedTax |
Field | New |
OrderLineItemType.TotalIncludeseBayCollectedTax |
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.
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 - 1131.
New TotalIncludeseBayCollectedTax boolean fields added to SoldReport and FeeSettlementReport responses to indicate if order and order line item amounts include eBay 'Collect and Remit' taxes. eBay 'Collect and Remit' taxes include US state-mandated sales tax and 'Good and Services' taxes that are applicable to Australian and New Zealand sellers. If this TotalIncludeseBayCollectedTax boolean field is returned as true, the tax amount shown in the Taxes.TaxDetails.TaxAmount field for each line item is reflected in the total line item cost and total order cost. The total order cost is shown in the OrderDetails.OrderTotalCost field, and the total order line item cost is shown in the OrderLineItem.TotalCost field. For a single line item order, the amounts in these two fields should be the same, but for a multiple line item order, the seller would need to view and add up the taxes shown in the Taxes.TaxDetails.TaxAmount field for each line item in the order.
As of early November, for orders subject to eBay 'Collect and Remit' taxes, PayPal began distributing order funds to the seller's account with the sales tax included. However, shortly after the order funds clear in the seller's account, the 'Collect and Remit' tax amount is pulled by PayPal from the seller's account and then disributed to the appropriate taxing authority. Previously, PayPal was stripping this 'Collect and Remit' tax from the buyer's payment and directly submitting this amount to the appropriate taxing authority, and this tax amount never showed up in the sellers account.
This change does not affect sellers that are already opted in to eBay managed payments. For these sellers, the sales tax amount will never be included in a seller payout.
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.
A new error code (21920255) was added to cover 'Buy it Now' prices that exceed the maximum thresdhold for a category. If a seller specifies the 'Buy it Now' price at a value above this threshold, this error code is returned and the seller is blocked from listing/revising an item.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1131 and Changed Functionality - 1131.
None for this release.
Documentation Changes and Errata - 1129
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 |
|---|---|---|
CollectionMethodCodeType |
Type | New (reserved for future use) |
TaxDetailsType.CollectionMethod |
Field | New (reserved for future use) |
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 early November, for orders subject to eBay 'Collect and Remit' taxes, PayPal will begin distributing order funds to the seller's account with the sales tax included. However, shortly after the order funds clear in the seller's account, the 'Collect and Remit' tax amount will be pulled by PayPal from the seller's account and then disributed to the appropriate taxing authority. Currently, PayPal is stripping this 'Collect and Remit' tax from the buyer's payment and directly submitting this amount to the appropriate taxing authority, and this tax amount never shows up in the sellers account.
eBay 'Collect and Remit' taxes include US state-mandated sales tax and 'Goods and Services' tax that is applicable to Australian and New Zealand sellers. To accomodate for these changes, the order management calls and the GetAccount call was updated. See the Changed Functionality section for more information about how these API calls are handling this logic change.
This change does not affect sellers that are already opted in to eBay managed payments. For these sellers, the sales tax amount will never be included in a seller payout.
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 - 1129.
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.
Beginning in early November, for orders subject to eBay 'Collect and Remit' taxes, PayPal will begin distributing order funds to the seller's account with the sales tax included. eBay 'Collect and Remit' taxes include US state-mandated sales tax and 'Goods and Services' tax that is applicable to Australian and New Zealand sellers. Due to this change, the following updates were made to OrderReport:
This change does not affect sellers that are already opted in to eBay managed payments. For these sellers, the sales tax amount will never be included in a seller payout. For sellers that are opted in to eBay managed payments, the 'Collect and Remit' tax will only be shown in the Transaction.eBayCollectAndRemitTaxes container, and not in the Transaction.Taxes. For sellers not opted in to eBay managed payments, both of these containers will appear in the response showing the 'Collect and Remit' tax details.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1129 and Changed Functionality - 1129.
None for this release.
Documentation Changes and Errata - 1113
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 new format for eBay orders has been implemented. The new format is a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. Unlike in the past, instead of just being known and exposed to the seller, these unique order identifiers will also be known and used/referenced by the buyer and eBay customer support. This new format will now appear in the order details section of the View Order Details page, in Seller Hub, in reports, and in email correspondence. Both the old format and the new order ID format will be supported in all API calls. See the Changed Functionality section for current details on how order IDs will work with Trading/Merchant Data API calls.
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 - 1113.
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 new format for eBay orders has been implemented, and this new format will now appear in the order details section of the View Order Details page, in Seller Hub, in reports, and in email correspondence.
Whether the old or new format for Order IDs is returned in OrderID fields in call responses is determined by the WSDL version being used and on the X-EBAY-API-COMPATIBILITY-LEVEL request header value. See below for more details on version control:
1113 to see the new order ID format in call responses. Note: The new order ID format will not be enabled to be returned with the SoldReport call. So, developers using SoldReport may want to consider using OrderReport instead.
Regardless of the WSDL version number or the X-EBAY-API-COMPATIBILITY-LEVEL, both old and new order ID formats can be used to identify an order in all call requests. These calls include the following:
eBay will support the old identifier format in legacy APIs until at least Q1 2020, but it is a good idea that developers integrate with the new format as soon as possible just for ease of management of orders, as only the new order ID format will be showing up elsewhere - Order Details, Seller Hub, email correspondence, etc.
If a user is using Version 1113 (or using an older version with the X-EBAY-API-COMPATIBILITY-LEVEL value set to '1113', the new order ID format will be seen in the OrderID field for the following call responses:
For the ExtendedOrderID field (returned in OrderReport), the new order ID format will be returned, regardless of the WSDL version number or compatibility level. The ExtendedOrderID was previously created to distinguish between legacy and REST API-based order identifiers. Now, with the rollout of the new order ID format, the same order identifiers will be used for both legacy and REST-based APIs, although the legacy APIs will support both the old and the new formats until 2020.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1113 and Changed Functionality - 1113.
The maximum length has been published for all occurrences of OrderID and ExtendedOrderID fields. The maximum length is 40 characters. Previously, the maximum length value was not stated in the API documentation. This maximum length value applies to both the old and the new order ID format.
Documentation Changes and Errata - 1107
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 |
|---|---|---|
OrderType.OrderLineItemCount |
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.
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 - 1107.
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.
Starting in June 2019, eBay will start changing the format of order identifier values. The new format will be a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. These order identifiers will be automatically generated after buyer payment, and unlike in the past, instead of just being known and exposed to the seller, these unique order identifiers will also be known and used/referenced by the buyer and eBay customer support.
For developers and sellers who are already integrated with the Trading API's order management calls, this change shouldn't impact your integration unless you parse the existing order identifiers (e.g., OrderID or OrderLineItemID), or otherwise infer meaning from the format (e.g., differentiating between a single line item order versus a multiple line item order). Because we realize that some integrations may have logic that is dependent upon the identifier format, eBay is rolling out this Trading API change with version control to support a transition period of approximately 9 months before applications must switch to the new format completely.
During the transition period, developers/sellers will use the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header in API calls to control whether the new or old OrderID format is returned in all Trading API call response payloads. The compatibility version is expected to be Version 1113. During the transition period and even after, the new and old OrderID formats will still be supported in all Trading API call request payloads. After the transition period (which will be announced), only the new OrderID format will be returned in all Trading API call response payloads, regardless of the Trading WSDL version used or specified compatibility level.
You can read more about this change in the Spring 2019 Seller Updates.
Starting July 1, 2019, the Good 'Til Cancelled renewal schedule will be modified from every 30 days to once per calendar month. For example, if a GTC listing is created July 5, the next monthly renewal date will be August 5. If a GTC listing is created on the 31st of the month, but the following month only has 30 days, the renewal will happen on the 30th in the following month. Finally, if a GTC listing is created on January 29-31, the renewal will happen on February 28th (or 29th during a 'Leap Year'). You can read more about this change in the Spring 2019 Seller Updates.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1107 and Changed Functionality - 1107.
The occurrence value of the CityName field of AddressType was incorrectly stated as 'Always' being returned. This was not correct, and the occurrence value was changed to 'Conditionally' returned instead. Although most addresses include a city name, some do not. For example, Singapore is an island city-state, and the CityName field would not be applicable to any address in Singapore.
For OrderReport, the buyer's email address will be returned (to the seller only) for orders less than two weeks old, but for orders that occurred more than two weeks in the past, the buyer's email address will no longer be returned. The Buyer.Email field will still be returned, but 'dummy data', such as Invalid Request will replace the actual email address.
Documentation Changes and Errata - 1099
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.
Beginning on March 18, 2019 on North American (US and Canada) and all Asian eBay sites, and followed shortly after (around April 1) on all European sites, the only supported listing duration for all new fixed-price listings will be Good 'Til Cancelled (GTC). Existing fixed-price listings with non-GTC durations will not be affected until it becomes time for the seller to relist that item, in which case the seller will have to relist it with the GTC listing duration.
As soon as this change rolls out, only the GTC enumeration value will be accepted in the Item.ListingDuration field of an Add/Revise/Relist/Verify listing call. Any other value that is passed into this field will be ignored, and the listing duration will be set to GTC automatically. The metadata in the GetCategoryFeatures call response will be updated to reflect this change. When using GetCategoryFeatures to retrieve supported listing durations for different listing types and categories for a particular eBay site, the seller includes the FeatureID field in the response and sets its value to ListingDurations.
Beginning May 1, 2019, eBay will no longer support electronic payments through a seller's Integrated Merchant Credit Card account. To accept online credit card payments from buyers, a seller must either specify PayPal as an accepted payment method, or opt in to the eBay Managed Payments program (currently only available to sellers in US).
Once this change takes affect, if IMCC is passed in as a value in an Item.PaymentMethods field of an Add/Revise/Relist call, this value will be ignored and dropped (and listing will possibly get blocked if IMCC is the only specified payment method). Once a seller is opted in to eBay Managed Payments, no Item.PaymentMethods values will need to be specified as eBay controls the accepted payment methods for each marketplace.
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 - 1099.
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 maximum number of item specifics that may be defined for a listing has increased from 30 to 45. In Add/Revise/Relist calls, item specific name-value pairs are specified through the ItemSpecifics.NameValueList container.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1099 and Changed Functionality - 1099.
Numerous documentation improvements were made for this release.
Documentation Changes and Errata - 1095
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.
Starting in mid-March 2019 on North American (US and Canada) and all Asian eBay sites, and followed shortly after (around April 1) on all European sites, the only supported listing duration for all new fixed-price listings will be Good 'Til Cancelled (GTC). Existing fixed-price listings with non-GTC durations will not be affected until it becomes time for the seller to relist that item, in which case the seller will have to relist it with the GTC listing duration.
GTC listings renew automatically every 30 days as long as the listing is showing quantity available (1 or more), an insertion fee may be charged for each 30-day period in which the listing is renewed. With GTC listings, it may also be a good idea to take advantage of the out-of-stock feature. With the out-of-stock feature, your fixed-price listing will retain its purchase and search history, but will display to potential buyers as being 'out of stock' if the quantity reaches 0. Then, the seller will just have to revise their listing with more inventory to make purchases possible again. The out-of-stock feature is set in My eBay Selling Preferences.
As soon as this change rolls out, only the GTC enumeration value will be accepted in the Item.ListingDuration field of an Add/Revise/Relist/Verify listing call. Any other value that is passed into this field will be ignored, and the listing duration will be set to GTC automatically. The metadata in the GetCategoryFeatures call response will be updated to reflect this change. When using GetCategoryFeatures to retrieve supported listing durations for different listing types and categories for a particular eBay site, the seller includes the FeatureID field in the response and sets its value to ListingDurations.
Beginning May 1, 2019, eBay will no longer support electronic payments through a seller's Integrated Merchant Credit Card account. To accept online credit card payments from buyers, a seller must either specify PayPal as an accepted payment method, or opt in to the eBay Managed Payments program (currently only available to sellers in US).
Once this change takes affect, if IMCC is passed in as a value in an Item.PaymentMethods field of an Add/Revise/Relist call, this value will be ignored and dropped (and listing will possibly get blocked if IMCC is the only specified payment method). Once a seller is opted in to eBay Managed Payments, no Item.PaymentMethods values will need to be specified as eBay controls the accepted payment methods for each marketplace.
The 2019 Early Seller Update is now available. Seller updates generally affect all or most sellers, but generally aren't specific to sellers and developers using the public APIs. This update covers the following topics:
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 - 1095.
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 only supported listing duration for all new fixed-price listings on the eBay Australia site is Good 'Til Cancelled (GTC). Existing fixed-price listings with non-GTC durations will not be affected until it becomes time for the seller to relist that item, in which case the seller will have to relist it with the GTC listing duration.
With this change, only the GTC enumeration value will be accepted in the Item.ListingDuration field of an Add/Revise/Relist/Verify listing call. Any other value that is passed into this field will be ignored, and the listing duration will be set to GTC automatically. The metadata in the GetCategoryFeatures call response has been updated to reflect this change to fixed-price listings.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1095 and Changed Functionality - 1095.
Added a note in the PictureDetails.PictureURL field about the 500 pixels requirement for all listing photos. With this requirement, all photos being added to a listing must be at least 500 pixels on its longest side. Any photos that do not meet this requirement will not be published to the listing.
Documentation Changes and Errata - 1091
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.
| Name | Part of Schema | Type of Change |
|---|---|---|
Item.MotorsGermanySearchable |
Field | Deprecated |
Item.ShippingTermsInDescription |
Field | Deprecated |
Seller.MotorsDealer |
Field | Deprecated |
SellerContactDetails.Phone2CountryCode |
Field | Deprecated |
SellerContactDetails.Phone2CountryPrefix |
Field | Deprecated |
SellerContactDetails.Phone2AreaOrCityCode |
Field | Deprecated |
SellerContactDetails.Phone2LocalNumber |
Field | Deprecated |
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 - 1091.
Previously, beginning with Version 1027, sellers on the US, UK, and DE sites gained the capability to accept Best Offers on auction listings. This capability is now also available to sellers on Canada sites (English and French), and to the eBay marketplaces in Australia, France, Italy, and Spain.
Sellers using auctions must choose between using the Best Offer or Buy It Now feature, as both features cannot be enabled on the same auction listing. If an auction listing is enabled with Best Offer, this feature will no longer be applicable once the listing receives its first qualifying bid.
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.
Sellers accepting Best Offers for an auction listing can now set the Best Offer Auto Reject threshold price (Item.ListingDetails.MinimumBestOfferPrice) to a dollar value higher than the auction starting price (Item.StartPrice).
Best Offers in auction listings are available to sellers on the US, Canada, UK, Germany, Australia, France, Italy, and Spain sites. Note that the Best Offer feature in auction listings is no longer applicable once the listing receives its first qualifying bid.
Previously, sellers using the Add/Revise/Relist calls had to include the CategoryMappingAllowed field and set its value to true. Now, eBay will do category mapping automatically (CategoryMappingAllowed field defaults to true instead of false, so sellers can now just omit the CategoryMappingAllowed field in an Add/Revise/Relist call.
With category mapping, eBay will automatically 'map' or 're-route' and outdated/deprecated Category ID to the updated/correct Category ID. The primary Category ID is specified in Add/Revise/Relist calls in the PrimaryCategory.CategoryID field, and the secondary listing category (if used) is specified in Add/Revise/Relist calls in the SecondaryCategory.CategoryID field. And if eBay does category mapping, the new Category IDs will appear in the response of a successful Add/Revise/Relist call.
The following fields under the SellerContactDetails container in an Add/Revise/Relist call have been deprecated since adding a secondary contact number is no longer supported for Classified Ad listings. If any of these fields are included in an Add/Revise/Relist call, they will be ignored:
The following two eBay Motors-related fields were deprecated. Previously, both of these boolean fields were set through an Add/Revise/Relist call.
The Item.ShippingTermsInDescription field used in Add/Revise/Relist calls is deprecated. If this field is included in an Add/Revise/Relist call, it will be ignored.
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features - 1091 and Changed Functionality - 1091.
None for this release.
Copyright © 2009–2019 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.