Amazon ECommerce Client

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By damitha nanda mangala kumarage
  • 13 Mar, 2008


The Amazon E-Commerce Service, "ECS", exposes Amazon's product data through an easy-to-use Web services interface. WSO2-WSF/C Solution Space provides an excellent command line tool called amazoneclient to consume this Web service from your command line shell(Linux or Windows). You can use the tool to search products, lookup selected items and finally add items to a shopping cart session created. The tool is easy to use and could be integrated to your scripts easily. amazoneclient internally uses WSF/C platforms command line Web services client tool called wsclient for doing Web service calls. For more information on wsclient, see my tutorial, Calling Web Services From The Shell. amazoneclient supports SOAP and REST like invocations.


Applies To

WSF/C 1.2.0, 1.2.1
Axis2/C 1.3.0
Environment Linux - Debian Etch/Lenny, Ubuntu, Fedora, Windows


Table of Contents


Installing amazoneclient and Getting Started

You can download a copy of amazoneclient from here: WSF/C-Solutions. You need to have wsclient installed in your system, in order to use amazoneclient. Click here to download and install wsclient.

Now, I will explain, in a step by step fashion, how to use amazoneclient effectively to do your transactions with Amazon e-commerce service.


Synopsis for amazonclient --subscription-id=<your amazon key> --op=<operation> --op-args=<key1:value1 key2:value2 ....>

For more information on each option do: --help

To interact with Amazon ecommerce service, you need to provide your amazon key that you can obtained from here, with the option --subscription-id. You need to provide the operation you want to invoke from ItemSearch, ItemLookup, CartCreate, CartAdd, CartModify or CartClear.

You also need to specify required arguments for the operation, under the option --op-args. After each amazoneclient invocation, you will see two files in the current directory from which you invoked the command. One is <op_name>.xml and the other is <op_name>Response.xml. The former contains your request message payload prepared by amazoneclient ready to be sent. The latter is the response file you received after invoking the Web service. For example, if you invoked the operation ItemSearch, your request file will be ItemSearch.xml and your response ItemSearchResponse.xml. There is also a options called dump, which you can use for testing purposes. What this does is to dump your request into the operation response file, in wire format (complete with headers etc), instead of actually sending the message through the wire.

The response from Amazon service is unformatted raw xml. The job of amazoneclient does not include displaying this response properly formatted. There are many tools out there better suited for that. May be you can use XSLT for that. Infact, comand line tools in the shell are designed to combine with other useful commands through pipes, redirection etc to provide powerful combinations. Each single tool excels at what it is designed to do. You can use a tool like xmlindent  to display the response in simple text format.

By default amazoneclient send requests in REST. In order to tell amazoneclient to use SOAP formatted messages, use --soap option.


So, you want to buy cool Amazon products using amazoneclient? I will guide you through a sample scenario where you purchase a couple of good books on Kundalini Yoga. Yoga is an Indian form of health improving exercises which is often mixed with spiritual/religious aspects. Kundalini is a perticular branch of that practice. Your first step would be to do a general search on books using keywords Kundalini and Yoga.

./ --subscription_id=<amazon key> --op=ItemSearch
--soap --op_args="Keywords:Kundalini_Yoga SearchIndex:Books" ; xmlindent
ItemSearchResponse.xml > item_search.txt

This will store the result in text format in a file named item_search.txt. The file contains a list of ASIN and other information. In amazon terms, ASIN is unique id to each product. Make sure to separate gaps in your Keywords with '_' character, rather than space.


Lookup Information of Selected Items -s<amazon key> -oItemLookup --soap
-a"ItemId:0789467704 ResponseGroup:OfferFull" ; xmlindent 
ItemLookupResponse.xml > item_lookup.txt

The result will be stored in a raw xml file ItemLookupResponse.xml, which is parsed by xmlindent to produce item_lookup.txt


Perform Effective Search/Lookup Using Browse Nodes

Now, there is a very effective way of searching for information in AWS using browse nodes. The idea is that from the ASIN's you obtained in the earlier search request's response you can do an item look up for upto 10 ASINs and obtain a list of browse nodes as following.

You need to specifiy the response group as BrowseNodes in your ItemLookup operation. Then we can survey the node id's returned in the response. --subscription-id=<amazon key> --op=ItemLookup
--soap --op-args="ItemId:0789467704,8185787158,0978649605,0393704750
ResponseGroup:BrowseNodes" ; xmlindent ItemLookupResponse.xml > item_lookup.txt

Now, you can select a suitable browse node from the above result, to do a more refined search: --subscription_id=<amazon key> --op=ItemSearch --soap --op_args="BrowseNode:16233641 SearchIndex:Books" ;  xmlindent ItemSearchResponse.xml > item_search.txt

Now you can do a ItemLookup operation again, for a selected item id from the above result: -s<amazon key> -oItemLookup --soap -a"ItemId: ResponseGroup:OfferFull"


Creating a Shopping Cart Session and Adding Items

Finally, when you decide to buy, you can do so by creating a shopping cart session as follows. -s<amazon key> --soap -oCartCreate
-a"Items=ASIN=0789467704:Quantity=1" ; xmlindent CartCreateResponse.xml >

CartCreateResponse.xml contain the PurchaseURL element which provides you a url to proceed with your purchasing of the items selected.


Modifying Items Already Added to the Shopping Cart

Before makinf the payment, if you still change your mind to do some changes to your cart, you can do so by calling the CartModify operation as follows:. -s<amazon key> --soap -oCartModify
-a"Items=CartItemId=UDUQ1SONAFNV2:Quantity=3" ; xmlindent
CartModifyResponse.xml > cart_modify.txt

Purchasing Products and Cleaning Up Your Cart

Finally, you can clear your cart session by: -s<amazon key> --soap -oCartClear ; xmlindent
CartClearResponse.xml > cart_clear.txt


wsclient is a command line tool from WSF/C Web services framework, which lets you consume Web services from the shell. This tool could be utilized from your shell scripts to create very powerful combinations of useful utilities. amazoneclient is one such utility which could be used to do transactions with Amazon ecommerce Web service application. It lets you search , lookup and add items to a shopping cart from Amazon stores.



  1. WSO2 WSF/C - WSO2 WSF/C is an Open Source framework for providing and consuming Web services
  2. Axis2/C- Axis2/C is an Apache Web Services Platform implemented in C language around which the WSO2 WSF/C is built.
  3. Making Web Services Work at Amazon
  4. Amazon Associates Web Service Best Practices



Damitha Kumarage, Senior Software Engineer at wso2, committer Apache Software Foundation, damitha at wso2 dot com

About Author

  • damitha nanda mangala kumarage
  • senior tech lead
  • wso2