Skip to main content

account APIv1.7.0

Account API release notes

Just getting started with the Account API? See the following documents for details on using this API:

The API release history

The following table lists the releases for the Account API:

Version Release Date Summary of Release
Version 1.7.0 2021-12-16 Added the new custom_policy resource with four new methods to create and manage Custom Policies.
Version 1.6.3 2021-06-21 Added support for multi-rate tables in the Spain (EBAY_ES) and France (EBAY_FR) marketplaces for the getRateTables method
Version 1.6.2 2021-04-20 Added support for multi-rate tables in the Germany (EBAY_DE) and United Kingdom (EBAY_GB) marketplaces for the getRateTables method
Version 1.6.1 2021-03-10 Added a new programTypeEnum value to support Partner Motors Program sellers
Version 1.6.0 2020-06-10 Added the kyc resource and the getKYC method to support eBay managed payments sellers
Version 1.5.0 2020-05-07 Added the onboarding resource that includes the getPaymentsProgramOnboarding method to the payments_program resource.
Version 1.4.0 2018-10-23 The getRateTables method has been expanded to include the Canada (EBAY_CA) and Italy (EBAY_IT) marketplaces.
Version 1.3.0 2018-07-25 Added the payments_program resource, which contains the single new method getPaymentsProgram.

Version 1.2.0

2018-05-31

The following updates have been made to Return policies:

  • An internationalOverride container was added, allowing you to specify different policy terms for international and domestic buyers.
  • The extendedHolidayReturnsOffered and restockingFeePercentage fields have been deprecated.
  • 14-day option for returnPeriod has been deprecated from most categories.
Version 1.1.0 2017-07-28 A new method, getRateTables, was added to the API.
Version 1.0.0 2017-04-20 An expansion to Version 1.0.0 that includes new support for the AU and CA eBay marketplaces.
Version 1.0.0 2016-10-19 Initial release of Version 1.

Version 1.7.0

This release adds one new resource with four new methods as described in Schema Changes.

Schema Changes

This release adds the custom_policy resource. This resource includes four new methods used to create and manage custom Product Compliance and Takeback policies:

  • createCustomPolicy - This method creates a new policy of a specified type for the selected marketplace.
  • getCustomPolicies - This method returns all policies of the specified type(s) for the selected marketplace.
  • getCustomPolicy - This method returns the policy specified by policy ID for the selected marketplace.
  • updateCustomPolicy - This method updates a specified policy for the selected marketplace.

Note: Custom Policies are currently supported only in the following eBay marketplaces: EBAY_DE, EBAY_CA, EBAY_AU, EBAY_US, and EBAY_FR.

Version 1.6.3

This release expands the marketplaces supported by the getRateTables method, as described below in Functionality changes.

Functionality changes

This release adds Spain (EBAY_ES) and France (EBAY_FR) to the list of marketplaces supported by the getRateTables method. The method now supports retrieving multi-rate tables created for the following marketplaces:

  • EBAY_AU
  • EBAY_CA
  • EBAY_DE
  • EBAY_ES
  • EBAY_FR
  • EBAY_GB
  • EBAY_IT
  • EBAY_US

Version 1.6.2

This release expands the marketplaces supported by the getRateTables method, as described below in Functionality changes.

Functionality changes

This release adds Germany (EBAY_DE) and United Kingdom (EBAY_GB) to the list of marketplaces supported by the getRateTables method. The method now supports retrieving multi-rate tables created for the following marketplaces:

  • EBAY_AU
  • EBAY_CA
  • EBAY_DE
  • EBAY_GB
  • EBAY_IT
  • EBAY_US

Version 1.6.1

This release adds a new enumeration value, as described below in Schema changes.

Schema Changes

This release adds a new PARTNER_MOTORS_DEALER enumeration value to the ProgramTypeEnum type. This new enumeration value allows sellers to opt-in to the Partner Motors Program, which enables registered business users to create motor vehicle listings.

Note: The Partner Motors Program is currently only supported in the UK marketplace, and sellers must complete the eBay Motors Pro registration flow in order to create motor vehicle listings.

Version 1.6.0

This release adds a new resource and method, as described below in Schema changes.

Schema Changes

This release adds a new kyc resource. This resource includes the getKYC method that allows eBay managed payments sellers to discover any 'Know Your Customer' KYC check action items.

Version 1.5.0

This release adds a new resource and method, as described below in Schema changes.

Schema Changes

This release adds a new onboarding resource to the payments_program resource. This resource includes the getPaymentsProgramOnboarding method that provides the ability to retrieves the seller's onboarding status of eBay managed payments for a specified marketplace.

Note: Managed payments availability: eBay managed payments is presently available in the US and Germany, and will roll out to Canada, UK, and Australia in July 2020.

Version 1.4.0

This release expands the marketplaces supported by getRateTables, as described below in Functionality changes.

Functionality changes

This release adds Canada (EBAY_CA) and Italy (EBAY_IT) to the list of marketplaces supported by getRateTables. The method now supports getting rate tables created for the following marketplaces:

  • EBAY_AU
  • EBAY_CA
  • EBAY_IT
  • EBAY_US

Note that both locales of the Canadian marketplace (en-CA and fr-CA) are supported by the getRateTables functionality.

Version 1.3.0

This release adds a new resource and method, as described below in Schema changes.

Schema changes

This release adds the getPaymentsProgram method to the new payments_program resource. This new method returns the seller's status with regards to whether or not they are opted-in to a payments program for the specified marketplace.

Version 1.2.0

This release adds a new container for international return policies. The new container allows sellers to set different terms for international returns (by default, international returns inherit the domestic return policy settings).

Schema changes

A new internationalOverride container was added to the return_policy resource. This container has several fields that let sellers define 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 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).

The schema for internationalOverride is as follows:

  "internationalOverride": {
    "returnMethod": "ReturnMethodEnum : [REPLACEMENT]",
    "returnPeriod": {
      "unit": "TimeDurationUnitEnum : [DAY]",
      "value": "integer"
    },
    "returnsAccepted": "boolean",
    "returnShippingCostPayer": "ReturnShippingCostPayerEnum : [BUYER,SELLER]"
  },

Changed functionality

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 restocking fees or hours for extended holiday returns with their return policies. With this, the following returnPolicy fields are deprecated with this release; any values supplied to these fields will not be read or returned:

  • extendedHolidayReturnsOffered
  • restockingFeePercentage

Simplified returns

Simplified returns changes the functionality of several fields within the return_policy resource and adds a new container (internationalinternationalOverride) with four new fields that mirror the domestic return policy fields. The following updates apply to the fields in both containers:

  • returnInstructions - This field is now valid for only the EBAY_DE, EBAY_ES, EBAY_FR, and EBAY_IT marketplaces.
  • refundMethod - This field is deprecated and now defaults to MONEY_BACK (other options are invalid).
  • returnMethod - This optional field is now valid in only in the US marketplace (any value supplied is ignored in other marketplaces). For createReturnPolicy and updateReturnPolicy, the only valid value for this field is REPLACEMENT (the value EXCHANGE has been deprecated). In existing policies, the value EXCHANGE is mapped to REPLACEMENT for domestic return policies. For international return policies, EXCHANGE is ignored (any supplied value is neither read nor returned).

  • returnsPeriod - This field is now required if the seller accepts returns for either domestic or international returns. The accepted values for this field have been streamlined and most categories now support only 30-day and 60-day options. 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 July 2018 with the return period values supported by each category, including the categories that support a 14-day return period.)

  • returnShippingCostPayer - This field becomes required if you set returnsAccepted to true 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 returnShippingCostPayer value. If a seller accepts returns, eBay automatically sets the international returnShippingCostPayer 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 (returnPeriod is set to Days_14) 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 returnPeriod (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 returnPeriod 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 returnsAccepted field to true for either a domestic or international return policy?
    • The returnPeriod, returnShippingCostPayer fields are all mandatory in all return policies. The refundMethod is deprecated (it is set to MONEY_BACK for all policies). returnMethod, now valid on only the US marketplace, can be set to REPLACEMENT if desired.
  • What happens if I try to revise a return policy that currently has a returnInstructions 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 returnMethod 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.1.0

This is a minor release of the API.

This API release contains the following updates and changes:

New methods

This release contains the following new method:

Version 1.0.0

The initial release of the Account API, Version 1.0.0, was released on October 19, 2016.

For a list of the methods, see the Account API Reference.

Expanded availability

Version 1.0.0 was updated on April 20, 2017 to expand support to the CA and AU eBay marketplaces (in addition to the US marketplace). The API is now supported by this list of marketplaces:

  • EBAY_AU
  • EBAY_CA
  • EBAY_US