Business Policies Management API Release Notes

You can find links to the eBay Business Policies Management API documentation in the top navigation bar. Information about the schema location is in the Schema Location section of the "Making an API Call" topic.

The following list provides pointers on how to join the eBay Developers Program and other useful information for for those new to the eBay APIs:

• How to Join the eBay Developer's Program
• eBay Developer Documentation Center
• eBay APIs - Quick Start
• eBay Trading API Guide

For a current list of known issues, see Site Status Updates and the Knowledge Base.

Version 1.1.0

Index of Changed Calls - v1.1.0

Schema Changes - v1.1.0

New Features - v1.1.0

Changed Functionality - v1.1.0

For a current list of known issues, see Site Status Updates and the Knowledge Base.

Index of Changed Calls - v1.1.0

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.

Changed Calls

• addSellerProfile
• setSellerProfile
• getSellerProfile

Schema Changes - v1.1.0

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.

New Features - v1.1.0

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 - v1.1.0.

International returns

A new internationalReturnPolicyInfo complex type was added to the returnPolicyProfile container. internationalReturnPolicyInfo has several fields that let sellers specify international return policies that differ from their domestic return policies (international returns are those that are shipped using an international shipping service).

Before this release, the single set of return policy fields represented the seller's return policies for both domestic and international returns. The preexisting return policy fields now define a seller's domestic return policy and the new international fields enable sellers to also define specific international return policies. (If a seller does not define specific international return policies, then any international returns will inherit the seller's domestic return policies).

Changed Functionality - v1.1.0

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.

This release launches a reorganization to eBay's return policies. To streamline the number of return variations, several fields were deprecated and others were added to make return policies simple to create and easy to maintain. For details on this roll out, see the Spring 2018 Seller Announcement, Simplified Returns.

Deprecated functionality

Starting with this release, sellers can no longer specify warranty information, restocking fees, or hours for extended holiday returns with their return policies. With this, the following returnPolicyProfile fields are deprecated with this release; any values supplied to these fields will neither be read nor returned:

• returnPolicyProfile.holidayReturns
• returnPolicyProfile.restockingFeeValue
• returnPolicyProfile.warrantyDurationOption
• returnPolicyProfile.warrantyOfferedOption
• returnPolicyProfile.warrantyTypeOption

Simplified returns

Simplified returns changes the functionality within the returnPolicyInfo container and adds a new container, internationalReturnPolicyInfo, with four new fields that mirror the fields in returnPolicyInfo. The following updates apply to the fields in both containers:

• description – This field is now valid for only the EBAY_DE, EBAY_ES, EBAY_FR, and EBAY_IT marketplaces.
• refundOption – You must set this value to MoneyBack for all eBay marketplaces except for the US marketplace (on EBAY_US, you can also set this to MoneyBackOrReplacement). The value MoneyBackOrExchange is retired. While currently accepted for existing policies, this value is now mapped to MoneyBackOrReplacement for domestic return policies, and the value is ignored in international return policies.
• returnsWithinOption – This field becomes required if you set ReturnsAccepted in either the domestic or international return policy. The accepted values for this field have been streamlined in that most categories now support only 30-day and 60-day values. The 3-day and 7-day options have been removed from the AU marketplace and the 14-day option has been removed from most categories.
  
  While you can create a return policy to support 14-day returns (for use in the US categories that employ this override), your request will fail if you attempt to use a 14-day return policy when listing items in categories that do not support this option.
  
  Call GetCategoryFeatures with DetailName set to ReturnPolicyDetails to review which categories allow a 14-day return period. (GetCategoryFeatures will be updated in mid-August 2018 with the return period values supported by each category, including the categories that support a 14-day return period.)
• shippingCostPaidByOption – This field becomes required if you set returnsAcceptedOption to ReturnsAccepted in either the domestic or international return policy. Valid values for this field are Buyer and Seller.

FAQ

• When will eBay begin enforcing the Simplified Returns policies?
  • Simplified Returns policy enforcement is currently scheduled to begin in late August. Check back here for the specific policy-enforcement date.
• How will existing listings that use a return policy which does not specify an international return policy be treated?
  • Any return policy that does not specify an international return policy will be treated as though the existing domestic return policy values apply to both domestic and international sales, with the exception of the shippingCostPaidByOption. If a seller accepts domestic returns, eBay automatically sets the international shippingCostPaidByOption value to Buyer and the international return policy will use the domestic return policy for all other settings. To avoid any confusion, sellers should explicitly set the international return policy fields using either the API or the UI site flow. International policies are not mandatory; however, once specified, international policies cannot be deleted (but they can be revised).
• What happens if I use a return policy with a 14-day return window (returnsWithinOption is set to 14-days) in an item that is listed in a category that no longer supports this option?
  • For API users, starting in late August, new listings and revisions to existing listings will be blocked if the target category doesn't support a 14-day return window. Also be aware that you cannot revise an item if it has a bid, a pending offer, or ends within 12 hours.
  • Changes to the eBay site are live and the site no longer offers non-valid return policy values for new item listings. However, you will be able to revise listings that specify a 14-day return window until the policy enforcement date.
  • The enforcement of the new return policy options will effect only new listings and listing revisions; existing listings will not be blocked when enforcement begins. When enforcement begins, however, GTC listings that reference a return policy that contains a non-valid returnsWithinOption (such as a 3, 7, or 14 day value) will be modified so it complies with the updated return policy options. To accomplish this, eBay will update any non-compliant return policies by changing the value of returnsWithinOption to the closest compliant value. In most cases, this means a 14-day return option will change to a 30-day return option. In this scenario, eBay will create a new policy (with a new policy ID) that contains the settings in the original policy. You can either delete this second policy or use it for items that you want to list in a category that supports a 14-day return option.
• What happens if I set only the returnsAcceptedOption field to ReturnsAccepted for either a domestic or international return policy?
  • The returnsWithinOption, shippingCostPaidByOption, and refundOption fields are mandatory in all return policies. The refundOption must be set to MoneyBack for all policies except for those targeting the US marketplace. For the US marketplace, refundOption can also be set to MoneyBackOrReplacement.
• What happens if I try to revise a listing that currently has a description field?
  • Only the DE, FR, IT, and ES marketplaces will continue to support this field. In the cases where this field is no longer supported but a value is present, the value is ignored. Note that where supported, you can populate this field even if you set returnsAcceptedOption to ReturnsNotAccepted.
• What happens if I specify values in the description or refundOption fields, but the marketplace no longer supports these fields?
  • In the cases where these fields are no longer supported, the values are ignored (they are neither read nor returned).
• What happens if I try to revise a listing that currently has a restocking fee (or other deprecated field) in its return policy?
  • Deprecated values are ignored and any present value is neither read nor returned.
• On the DE marketplace, can I continue to use Months_1 as a value for returnsWithinOption (will either Days_30 or Months_1 be accepted)?
  • For the DE marketplace, the value Months_1 will continue to be accepted for the next 18 months. If this value is specified, it is stored as Days_30. After 18 months, a value of Months_1 will throw a blocking error.

Version 1.0.0

This is the first release of the Business Policies Management API.

Index of Changed Calls - 1.0.0

This section lists calls that have changed or are new with this API release.

New Calls

The following calls are included in the initial v1.0.0 release of the Business Policies Management API: