Changes to the Product Advertising API


In order to ensure that the features offered by the Product Advertising API are most relevant to the advertising use case, we plan to implement the following changes to the API, which will be effective 11/1/2011. This guide describes the changes, the impact it may have on your websites/applications and helps you determine if you need to make any changes.

The new Product Advertising API interface definition (WSDL) is now available. While your application may continue to operate after 11/1/2011 using older WSDLs, we will stop supporting all previous versions on 02/21/2012. Please upgrade to the latest WSDL before that date to ensure the continued operation of your application.

Product Advertising API Change Details

The following changes will take effect on 11/1/2011:

Associate Tag Parameter: Every request made to the API should include a valid Associate Tag. Any request that does not contain a valid Associate Tag will be rejected with an appropriate error message. For details on the Associate Tag parameter, please refer to our Developer guide.

Seller Operations: The SellerLookup, SellerListingLookup and SellerListingSearch operations will be deprecated. All requests for these operations will be rejected with a corresponding error message.

ItemPage Parameter: For the ItemSearch operation, the ItemPage parameter will have a maximum value of 10 instead of 400. The limit for the “All” search index will continue to be 5 pages. A new element “MoreSearchResults” will be added to ItemSearch responses, containing a link to the Amazon website where your customers can see additional search results beyond the ItemPage limit. All requests for ItemPage greater than 10 will be rejected with an appropriate error message.

Merchants search index: The “Merchants” search index will be deprecated. All requests for this search index will be rejected with an appropriate error message.

ItemAttributes Response group: Selected ItemAttributes that are not relevant to the broader product advertising use case will be deprecated, for the new list of supported attributes, please see the new WSDL.

Offers: The selection of offers is simplified and limited to the most frequently used use cases. You will no longer need to guess which combination of Merchant ID and Condition will return the most relevant offer or make multiple trial-and-error calls.

  • The OfferPage parameter is no longer supported and will be ignored.
  • A new element “MoreOffers” will be added to the Offers response group, containing a link to the offers page on Amazon.
  • Select elements from the Offers response group are being removed:
    • Merchant ID, Merchant Location
    • Total Feedback Pages, Total Feedback, Average Rating
    • Exchange ID
    • Quantity
    • Sub Condition, Condition Note, Will Ship Expedited/International
    • Quantity Restriction, Sales Restriction
    • ISPU Store Address, Store Hours
    • IsFulfilledByAmazon, IsMAPViolated, MAP Policy
  • Please refer to our Developer guide for details on the expected behavior of the API for various input parameters for the Offers response group.

Impact on your applications

With the exception of the deprecated operations, search index and the Associate Tag requirement, all the above changes are designed to be backward compatible. Please note that:

  • No new request parameters are required to take advantage of these changes.
  • To use the new elements that we have added, you must use Version 2011-08-01 of our schema.
  • Most elements slated for deprecation are marked as “optional” in our schema; if your application handles optional elements correctly, you need not make any changes.

If your application currently accesses the API without passing a valid Associate Tag, such requests will be rejected. Please make the necessary change in your application to include your Associate Tag in all requests to the API.

If your application uses Offers or Variations response groups then the following guidelines apply to you:

  • If your application does not explicitly use MerchantId, the default behavior has been changed to provide you with offer data even if Amazon does not have an offer for a specific item. If you want only the Amazon offer for an item, you will have to specify MerchantId=Amazon.
  • If your application has complex Offer selection logic (i.e. uses MerchantId, Condition or OfferPage parameters), it is recommended that you remove these parameters from the API call. The API will automatically find and return the most relevant offer for the product. Use the Offer Summary Response Group to find how many offers for each condition are available for the product and the MoreOffers link to refer customers to Amazon as needed.
  • If your application selects Variations using the MerchantId parameter, it is recommended that you remove these parameters from the API call. The API will, by default, return all Variations and the best offer for each variation.
  • If you have logic to page through offers using the OfferPage parameter, you should disable this.

If your application uses ItemSearch then the following may apply to you:

  • If your application supports the Merchants search index, you should disable it.
  • If your application attempts to fetch more than 10 pages of search results, you should instead use the MoreSearchResults link to refer customers to the Amazon website.