Amazon 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: