Table Of ContentAmazon Associates Web
Service
Developer Guide
API Version 2008-04-07
AmazonAssociatesWebServiceDeveloperGuide
AmazonAssociatesWebService:DeveloperGuide:Formerly
knownasAmazonE-CommerceService(ECS)
Copyright©2004-2008AmazonWebServicesLLCoritsaffiliates.Allrightsreserved.
AMAZONandAMAZON.COMareregisteredtrademarksofAmazon.com,Inc.oritsAffiliates.Allothertrademarksarethe
propertyoftheirrespectiveowners.
ThirdPartyInformation:Thisguidecontainslinkstothird-partywebsitesthatarenotunderthecontrolofAmazon.com,and
Amazon.comisnotresponsibleforthecontentofanylinkedsite.Ifyouaccessathird-partywebsitementionedinthisguide,then
youdosoatyourownrisk.Amazon.comprovidestheselinksatyourownconvenience,andtheinclusionofthelinkdoesnot
implythatAmazon.comendorsesoracceptsanyresponsibilityforthecontentonthosethird-partysites.
Thisbookwaslastupdated2008-05-19.
AmazonAssociatesWebServiceDeveloperGuide
Table of Contents
What'sNew......................................................................................................................................1
ProgrammingGuide.........................................................................................................................3
Welcome.......................................................................................................................4
Audience..............................................................................................................4
HowThisGuideisOrganized.............................................................................5
RelatedDocuments.............................................................................................5
GettingSetUp..............................................................................................................5
GettingRegistered...............................................................................................5
BecominganAmazonAssociatesWebServiceDeveloper......................6
AWSAccessKeyID........................................................................6
SecretAccessKey............................................................................6
RegisteringwithAmazonPayments..........................................................7
BecominganAssociate..............................................................................7
BecomingaSeller......................................................................................7
BecomingaMarketplaceProMerchant....................................................7
BecominganAmazonAdvantageSeller...................................................8
ReadingAmazon'sLicensingAgreement...........................................................8
IntroducingE-CommerceandWebServices................................................................9
WhatisE-Commerce?......................................................................................10
WhatisaWebService?....................................................................................10
WhatisXML?...................................................................................................11
XMLSyntax............................................................................................11
XMLStructures.......................................................................................12
UsingXML..............................................................................................12
WhatisaWSDL?..............................................................................................12
RestrictedPartsoftheWSDL..................................................................12
AnatomyofaWSDL...............................................................................13
RequestDefinitions........................................................................15
ResponseDefinitions.....................................................................16
ResponseGroupDefinitions.................................................16
PortType...............................................................................17
Binding...........................................................................................17
Service............................................................................................18
WSDLLocation.......................................................................................18
WhatisaSchema?............................................................................................19
SchemaLocations....................................................................................19
AmazonAssociatesWebServiceTerminologyandBasicConcepts.........................20
TheMarketplace................................................................................................20
WhatIstheAmazonAssociatesWebService?................................................21
HowDoIMakeMoneyUsingAmazonAssociatesWebService?..................22
InternationalLocales.........................................................................................22
VendorsonAmazon..........................................................................................22
Associates................................................................................................24
Sellers......................................................................................................25
AmazonAdvantageSellers............................................................26
IndividualandProMerchantSellers..............................................26
IndividualSellers...........................................................................27
ProMerchantSellers......................................................................28
Merchants................................................................................................28
Merchants@ProMerchants...........................................................29
Merchants@Sellers.......................................................................29
ItemsforSale....................................................................................................31
ItemIdentifiers.........................................................................................31
AmazonAssociatesWebServiceDeveloperGuide
OtherItemIdentifiers.....................................................................32
SummaryofAmazonAssociatesWebServiceOperations..............................33
FindItems................................................................................................34
FindOutMoreAboutSpecificItems......................................................34
ShoppingCart..........................................................................................34
CustomerContent....................................................................................35
SellerInformation....................................................................................35
OtherOperations......................................................................................35
AmazonAssociatesWebServiceDeveloperCommunity................................36
AmazonAssociatesWebServiceDeveloperAids...........................................36
VisualIntroductiontoAmazonAssociatesWebService...........................................37
FindingItems.....................................................................................................38
FindingOutMoreAboutanItem......................................................................38
GettingSellerInformation................................................................................39
ImplementingaShoppingCart.........................................................................39
OrganizationofItemsforSaleonAmazon................................................................40
ItemOrganization..............................................................................................40
BrowseNodes...................................................................................................41
BrowseNodeProperties..........................................................................42
RootCategory................................................................................42
BrowseNodesandItems.........................................................................43
BrowseNodeIDs.....................................................................................44
BrowseNodesandSearchIndices...........................................................45
FindingBrowseNodes............................................................................45
SearchIndices...................................................................................................47
SearchIndicesandLocales......................................................................48
Variations..........................................................................................................50
VariationParents.....................................................................................50
VariationDimensions..............................................................................52
Collections.........................................................................................................53
ParentandChildCollectionItems...........................................................54
Tags...................................................................................................................55
Lists...................................................................................................................56
AmazonAssociatesWebServiceOperationsandLists..........................57
URLsforLists.........................................................................................57
URLsforWishLists.......................................................................57
URLsforListmaniaLists...............................................................57
URLsforWeddingRegistryandBabyRegistryLists.....................58
FindingListIDs.......................................................................................58
Accessories........................................................................................................58
MakingRequestsandUnderstandingResponses.......................................................60
MakingRESTRequests....................................................................................60
MakingSOAPRequests....................................................................................65
UnderstandingResponses.................................................................................73
FindingItemstoBuy..................................................................................................81
SearchOperations.............................................................................................81
ItemsYouCannotBuy......................................................................................82
FindingItemsSoldbyMerchants.....................................................................83
RequiredItemSearchParameters.............................................................83
CommonItemSearchParameters............................................................84
ReturningOnlyAvailableItems....................................................85
InaccurateAvailabilities.......................................................85
AvailabilityParameterRestrictionsandConstraints............86
PowerSearches........................................................................................86
PowerSearchSyntax.....................................................................87
PowerSearchOperators.......................................................88
PowerSearchTips.........................................................................89
SearchingUsingTextStream...................................................................89
AmazonAssociatesWebServiceDeveloperGuide
UsingSearchBinstoFindItems.......................................................................89
NarrowByAttribute.................................................................................90
NarrowByValues....................................................................................92
NarrowByValuesPerSearchIndex..............................................92
FindingItemsSoldbySellers...........................................................................95
FindingItemsUsingBrowseNodes..................................................................97
TraversingtheBrowseNodeHierarchy..................................................98
UnderstandingBrowseNodeResultsWhenDrillingDown....................99
FindingItemsonLists.....................................................................................101
FindingtheItemsUsingtheCustomerID.............................................102
FindingCustomerInformation........................................................................103
CustomerContentSearch........................................................................103
CustomerContentLookup.......................................................................104
MotivatingCustomerstoBuy...................................................................................104
UsingImages...................................................................................................105
UnderstandingImagesSuppliedbyAmazonAssociatesWebService.105
ImageDetails...............................................................................107
MultipleImagesVersusVariationImages............................................108
ImageSets..............................................................................................110
ImageSetCategories....................................................................110
RetrievingImages........................................................................111
ManipulatingImageURLs....................................................................112
AddingAdditionalViews............................................................112
SpinningImages.................................................................114
Promotions......................................................................................................115
PromotionCategories............................................................................116
BenefitandEligibleItems.....................................................................117
TypicalResponseElementsUsed..........................................................118
RSSFeedsforPromotions.....................................................................119
CustomerandSellerReviews.........................................................................119
GettingCustomerReviews....................................................................120
GettingEditorialReviews......................................................................120
GettingSellerFeedback.........................................................................121
ReturningAdditionalSellerReviews..........................................123
SuggestingOtherItemsSoldbytheSeller......................................................123
SuggestingSimilarItemstoBuy.....................................................................124
FindingSimilarItemIDs.......................................................................124
ReturningItemsSimilartoCartItems...................................................125
UsingSimilarityLookup........................................................................126
SpecifyingMultipleItems............................................................126
FilteringSimilarItems...........................................................................127
SimilarVersionsoftheSameItem........................................................127
RecommendingOtherItemsSoldbytheSameSeller....................................128
TopSellers.......................................................................................................129
GettingTopSellersFromtheShoppingCart........................................131
NewReleases..................................................................................................131
SortingbyPopularity,Price,orCondition......................................................132
SuggestingItemsonaCustomer'sWishList..................................................133
ReturningPriceandAvailabilityInformation..........................................................135
ReturningPrices..............................................................................................135
OfferSummaries....................................................................................136
ReturningMoreInformationAbouttheOffer.......................................136
ProvidingPriceRangesforProductCategories....................................137
ItemsThatDoNotHaveOffers.............................................................138
DeterminingParentItems......................................................................138
ReturningOffersFromItemVariations................................................138
VariationDimensions............................................................................139
DeterminingAvailability.................................................................................140
AmazonAssociatesWebServiceDeveloperGuide
AvailabilityValues................................................................................141
CheckingforanOfferListingID..........................................................142
DeterminingtheAvailabilityofItemsSoldbySellers..........................143
WorkingWithRemoteShoppingCarts....................................................................144
ShoppingCartConcepts..................................................................................144
CartIdentifiers.......................................................................................144
MergingLocalandRemoteShoppingCarts.........................................147
RemoteShoppingCartTasks..........................................................................150
CreatingaRemoteShoppingCart.........................................................150
SpecifyingtheItemsintheCartCreateRequest..........................151
AssociateTagParameter...............................................................152
MergeCartParameter...................................................................153
UsingValuesReturnedbyCartCreateinOtherCartOperations 153
ModifyingtheItemsinaRemoteShoppingCart........................154
AddingItemstoaCart.................................................................154
AddingItemsasSavedForLater.......................................155
AddingListItemstoaCart................................................156
RemovingItemsFromaCart.......................................................156
ChangingtheMergeCartValue...................................................156
ReturningtheContentsofaCart...........................................................156
AddtoCartForm............................................................................................157
PurchasingtheItemsinaRemoteShoppingCart....................................................159
OrderPipeline.................................................................................................159
ImplementingtheProceedtoCheckoutButton..............................................160
PurchaseURL.........................................................................................160
BuyNowForm................................................................................................161
TrackingTransactions...............................................................................................162
UsingTransactionLookup...............................................................................162
SplitShipmentTransactions............................................................................163
HandlingErrorsandTroubleshootingApplications.................................................163
SyntaxandParameterErrors...........................................................................163
ProcessingError.....................................................................................164
ResultsandErrors..................................................................................165
RetrievingErrors.............................................................................................165
TroubleshootingApplications.........................................................................165
ErrorCodesandMessages..............................................................................166
ErrorCodes............................................................................................166
ErrorMessages......................................................................................167
BestProgrammingPractices.....................................................................................173
LocaleConsiderations...............................................................................................175
Locales............................................................................................................176
GeneralDifferences.........................................................................................176
AssociateIDs...................................................................................................177
ShippingRestrictions......................................................................................177
APIReference..............................................................................................................................178
Operations.................................................................................................................178
BrowseNodeLookup........................................................................................179
ResponseTags.......................................................................................179
ResponsetoSampleRequest.................................................................180
FindingBrowseNodeValues................................................................181
RelatedOperations.................................................................................182
CartAdd...........................................................................................................182
CartClear.........................................................................................................187
CartCreate........................................................................................................189
SpecifyingtheItems..............................................................................190
CartGet............................................................................................................195
CartModify......................................................................................................198
CustomerContentLookup................................................................................203
AmazonAssociatesWebServiceDeveloperGuide
CustomerContentSearch..................................................................................206
Help.................................................................................................................208
ItemLookup.....................................................................................................211
ItemIdentifiers.......................................................................................211
ItemSearch.......................................................................................................221
ListLookup......................................................................................................237
SupportedListTypes.............................................................................238
ListSearch........................................................................................................242
SupportedListTypes.............................................................................242
SellerListingLookup........................................................................................246
SellerListingSearch.........................................................................................249
SellerLookup...................................................................................................252
UsingaMerchantID.............................................................................253
SimilarityLookup............................................................................................255
TagLookup......................................................................................................259
TransactionLookup..........................................................................................262
FindingaTransactionID.......................................................................262
CommonRequestParameters...................................................................................265
ResponseGroups......................................................................................................268
AccessoriesResponseGroup..........................................................................268
AlternateVersionsResponseGroup................................................................270
BrowseNodeInfoResponseGroup..................................................................272
BrowseNodesResponseGroup.......................................................................274
CartResponseGroup......................................................................................275
CartNewReleasesResponseGroup.................................................................278
CartTopSellersResponseGroup.....................................................................279
CartSimilaritiesResponseGroup....................................................................280
CollectionsResponseGroup...........................................................................282
CustomerFullResponseGroup.......................................................................284
CustomerInfoResponseGroup.......................................................................285
CustomerListsResponseGroup......................................................................287
CustomerReviewsResponseGroup................................................................288
EditorialReviewResponseGroup...................................................................289
HelpResponseGroup......................................................................................290
ImagesResponseGroup..................................................................................292
ItemAttributesResponseGroup......................................................................295
ItemIdsResponseGroup.................................................................................301
LargeResponseGroup....................................................................................302
ListFullResponseGroup.................................................................................310
ListInfoResponseGroup................................................................................312
ListItemsResponseGroup..............................................................................314
ListmaniaListsResponseGroup......................................................................316
ListMinimumResponseGroup.......................................................................317
MediumResponseGroup................................................................................318
MerchantItemAttributesResponseGroup.......................................................326
NewReleasesResponseGroup........................................................................327
OfferFullResponseGroup..............................................................................328
OfferListings...................................................................................................330
OffersResponseGroup...................................................................................332
OfferSummaryResponseGroup.....................................................................336
PromotionDetailsResponseGroup.................................................................338
PromotionTypes....................................................................................338
PromotionSummaryResponseGroup.............................................................341
PromotionTypes....................................................................................341
RelatedItemsResponseGroup........................................................................343
RequestResponseGroup................................................................................345
ReviewsResponseGroup................................................................................347
SalesRankResponseGroup............................................................................348
AmazonAssociatesWebServiceDeveloperGuide
SearchBinsResponseGroup...........................................................................350
SellerResponseGroup....................................................................................354
SellerListingResponseGroup.........................................................................356
SimilaritiesResponseGroup...........................................................................358
SmallResponseGroup....................................................................................359
SubjectsResponseGroup................................................................................361
TaggedGuidesResponseGroup......................................................................362
TaggedItemsResponseGroup........................................................................363
TaggedListmaniaListsResponseGroup..........................................................365
TagsResponseGroup......................................................................................367
TagsSummaryResponseGroup......................................................................369
TopSellersResponseGroup............................................................................370
TracksResponseGroup..................................................................................371
TransactionDetailsResponseGroup...............................................................373
VariationMinimumResponseGroup..............................................................375
VariationDimensions............................................................................375
VariationsResponseGroup.............................................................................377
VariationDimensions............................................................................377
VariationImagesResponseGroup...................................................................379
VariationMatrixResponseGroup...................................................................381
VariationOffersResponseGroup....................................................................383
VariationSummaryResponseGroup...............................................................385
ResponseElementsCommontoAllResponseGroups............................................387
ItemSearchSortValuesByLocale...........................................................................433
SortValuesforCA..........................................................................................433
SortValuesforDE..........................................................................................435
SortValuesforFR...........................................................................................443
SortValuesforJP............................................................................................448
SortValuesforUK..........................................................................................455
SortValuesforUS..........................................................................................462
SearchIndexandItemSearchParameterCombinations...........................................476
SearchIndex-ItemSearchParameterCombinationsforCA............................476
SearchIndex-ItemSearchParameterCombinationsforDE.............................480
SearchIndex-ItemSearchParameterCombinationsforFR.............................487
SearchIndex-ItemSearchParameterCombinationsforJP..............................492
SearchIndex-ItemSearchParameterCombinationsforUK............................497
SearchIndex-ItemSearchParameterCombinationsforUS.............................504
SearchIndexSupportbyLocale...............................................................................516
BrowseNodeIDs......................................................................................................518
Glossary.......................................................................................................................................524
Index.............................................................................................................................................529
AmazonAssociatesWebServiceDeveloperGuide
What's New
ThisWhat'sNewisassociatedwiththe2008-04-07releaseoftheAmazonAssociatesWebService
(AmazonAssociatesWebService).Thisguidewaslastupdatedon2008-05-19.
Thefollowingtabledescribestheimportantchangestothisguide.
Change Description ReleaseDate
Theformatofthe ADetailPageURLiscomposedofmanyparts.Oneisthe 2008-05-19
valuesofthelocation locationparameter.Theformatoflocationvalueshas
parameterina changed.Itwasformatedas:
DetailPageURLhas
location=/o/ASIN/B00005R09P
changed.
Thesamevalueinthenewformatis:
location=/Programming-Perl-2nd-Larry-Wall/dp/B00005R09P
TheRelatedItems Inthepast,youcouldusetheRelatedItemsresponsegroup 2008-05-19
responsegroupcan onlywithItemLookup.Thesamefunctionalityhasnowbeen
nowbeusedwith extendedtoItemSearch.Whenusingthisreponsegroup,you
ItemSearch. mustalsoincludeintherequesttheparameter,
RelationshipType,whichspecifiesthetypeofrelationship.
Currently,therearefourteenpossiblevalues.
RelatedItemPageisanadded,optionalparameterthatyouuse
toretrieveadditionalpagesofrelateditems.
TheJPlocalehas ThenewItemSearchsortvalues,releasedateand-releasedate, 2008-04-07
newsortparameters, performthesamefunctionastheprevioussortvalues,
releasedateand release-dateand-release-date,whichcontinuetoworkand
-releasedate,forthe sortaccordingtoreleasedate.-releasedatemeansthatthe
searchindices: itemsaresortedsuchthatthelastreleaseditemislistedfirst.
software,
videogames,kitchen,
andtoys.
ListLookuphasanew IfyousetIsOmitPurchasedItems=1inaListLookuprequest, 2008-04-07
parameter, itemsonawishlistthathavebeenpurchasedwillnotbe
IsOmitPurchasedItems. returnedintheresponse.Onlythoseitemsthathavenotbeen
purchasedorthoseforwhichtheentirequantityhasnotbeen
purchasedarereturned.
APIVersion2008-04-07
1
AmazonAssociatesWebServiceDeveloperGuide
Change Description ReleaseDate
ListLookupnow Customersassignapriorityvaluetoeachitemtheyaddto 2008-04-07
returnsthepriority theirwishlist.Thevaluescanbehighest,high,medium
valuesoftheitemson (default),low,andlowest.InaListLookupresponse,these
awishlist. valuesarereturnedinthe<Priority>tag.
Anewsort Customersassignapriorityvaluetoeachitemtheyaddto 2008-04-07
parameter,Priority, theirwishlist.Thevaluescanbehighest,high,medium
enablesListLookup (default),low,andlowest.WhenyouincludeSort=Priorityin
tosorttheresultsby aListLookuprequest,theitemsaresortedfromhighestto
priority. lowestpriority.
The TheIngredientSetElementhasbeenreturnedwiththe 2008-04-07
IngredientSetElement ItemAttributesresponsegroup.Now,thesamevaluesarealso
isnowreturnedwith returnedwiththeMerchantItemAttributesresponsegroup.
the
MerchantItemAttributes
responsegroup.
Theformatofimage Thesameimagesarereturnedasbeforebuttheformatoftheir 2008-04-07
URLshaschanged. URLshaschanged.Previously,imageURLslookedlike
11dleRLvCkL.jpg.Now,theylooklike
41koyUV4srL._SL110_.jpg.Theappendedvalue._SL110_,
specifiesthesizeoftheimage.ValidvaluesareSL500,
SL160,SL110,SL75,andSL30.Thesenumericalvaluesrefer
tothenumberofpixelsonthelongestsideoftheimage.
TheItemAttributes ThenewtagsreturnedfordigitalitemsincludeLongSynopsis, 2008-04-07
responsegroupnow ShortSynopsis,Studio,SeasonSequence,OriginalAirDate,
returnsadditional EpisodeSequence,StartYear,andGenre.
informationabout
digitalitems.Digital
itemsarefoundinthe
searchindices
KindleStore,
MP3Downloads,and
UnboxVideo.
APIVersion2008-04-07
2
Description:product: books. Soon after the start of Amazon, the garage became too small to run the business. Since 1995, the number of sellers has grown, the types of .. Many sellers on Amazon are unknown to the buyer. For another good source of information is the Amazon Associates Web Service blog, go to.