Shopping Basket


Cart empty

Log In

Find Us Elsewhere


Forum Search


This content plug-in for Joomla! embeds Amazon product information into a content article, with affiliate links that earn money for you when a user clicks the link and makes a purchase from Amazon. The plugin works for Joomla 1.5x to 3.

You can buy the plugin here.

You can view some examples here.


You will need:-

  1. An affiliate tag (associates id) for each Amazon country site that you want to show products from.
  2. AWS Access key and secret key for the Amazon product advertising API

Please read the links above, getting the correct keys is by far the hardest part of the setup and the thing that trips most users up, the rest of the setup is normally easy.

Once you have the associates id and API keys you supply them as setup options in the AmazonWS API system plugin

How It Works

The plugin sends a signed request (known as a REST request) to the Amazon server. The request is signed using a public key and a secret key known only to yourself - you obtain both these when you sign up for your AWS account. An unsigned request will be ignored, a correctly signed one will return Amazon product information as an XML feed, which the plugin then parses to obtain the information.

There are two main types of request that return product information:-

  • an item lookup request will return results for up to 10 items identified by their ASIN number, which is a unique identifier that Amazon attaches to every product it sells. For books the ASIN is identical to the 10 digit ISBN number
  • an item search request will use keywords to search the product database, which can be restricted to a particular search index, such as books, or be a search of the entire database. Up to 10 results will be returned per search.

The plugin can support either type of request.


There are two ways to use the plugin to embed Amazon products, using the Joomla article metatags to search the Amazon product database; or using a simple embedding code to place the results in an article or elsewhere. Many extensions such as K2 and Virtuemart will also support Joomla content plugins, so the use of embedding code means that you can add product information to a wide variety of content.

Using Article Metatags

The easiest way to use the plugin is to simply select the section, category or individual articles using the plugin manager. The plugin will be automatically rendered, and the output appended to the selected articles. The plugin will use the article metatag keywords to run a keyword search on the selected Amazon site. If you want to display a specific product you can supply the ASIN as a metatag, however you may find that using embedding code is more reliable.

You can use the plugin parameters to select the number of tags to use. The default is 2, and it is usually good to use one or two at most, the reason being that Amazon will only return search results that contain all keywords, if too many are used then it unlikely to return any results.

Using Embedding Code

You can also use embedding code to render the plugin for an individual article. This allows you to have greater control over the results returned, including allowing you to select an individual product by ASIN or ISBN (10 digit).

To embed the plugin, use the following format:


with the parameters specified as a list separated by semi-colons (;). yes can be replaced by no to switch the options off, replace xxxxxxxx with the relevant values. See the section below for a summary of the available parameters.

Because you have specified the itemId the plugin will use this to perform an item lookup. Note that you do no normally need to specify all these parameters, you can set most options in the Joomla plugin manager, you only need to specify the parameters in the embedding code if you want to override the plugin manager options. The most common form for an item lookup request is simply:-




the list can include up to 10 values for the itemId, as a comma separated list. You can find the Amazon itemId by looking at the Amazon listing for your chosen item. It will be listed under product details. It will be the value of the ASIN number, except in the case of books, where it will be the ISBN-10 number.

Item Search

If you leave out the itemId parameter the plugin will send a search request instead. In this case you must at least include an author, title or keywords parameter, for example


You can include as many keywords as you want, as a comma-separated list. However it is not a good idea to include more than 2 or 3 at most, the reason being that Amazon will only return results that match ALL keywords, so that the more you include, the fewer results will match.

Search Index

You can control the type of products returned by including a searchIndex parameter, for example


If you are doing a keyword search, the search index does not need to be specified, because the default value of 'All' will be used, although you can include it. However, if you are using an author or title search, you will need to specify Books or another category where this kind of search is supported (see the Amazon documentation for further details). For example


The available values for searchIndex are:-


Not all of these are available for all Amazon countries. If you get an error message saying that the search index is invalid, it means that the one you are using does not exist for the country database you are using.

Summary of Plugin Parameters

Summary of Plugin Shortcode Parameters
NameDefault ValuePossible ValuesDescription
itemId     10 character product ASIN or ISBN, or can be a comma-separated list of up to 10 ASINs, use for item lookup which fetches specific products
keywords     one or more keywords for item search, this will search all the product information for the keywords
searchIndex All listed above used to limit the keyword search to specific product type
showPrices yes yes, no show the Amazon list price
showSalePrices yes yes, no show the Amazon sale price
showAmountSaved yes yes, no show the amount save (off list price)
showNewOfferPrices yes yes, no show the lowest new offer price
showUsedOfferPrices yes yes, no show the lowest used offer price
showCollectiblePrices yes yes, no show the collectible price
showRevs yes yes, no show the Amazon customer reviews
showEditorial yes yes, no show the editorial review (this is basically the product description, usually the same as on the Amazon product page)
country com com, de,, fr,, ca, cn, it, in, es,, the Amazon country database from which you want to display results - normally you will set this once in the plugin options rather than using short code, but you can override this using short code eg country=de
associateId     the tracking (affiliate id) to include in the product links - normally you will set this once in the plugin options, but you can override it in the short code eg associateId=myname-21
author     use instead of keywords parameter to make a search only of authors eg author=Rowling
brand     use instead of keywords parameter to make a search only of brand information eg brand=Apple
manufacturer     use instead of keywords parameter to make a search only of manufacturer information eg manufacturer=Samsung

use instead of keywords parameter to make a search only of publisher information eg publisher=Blackwell

title     use instead of keywords parameter to make a search only of title, notice you don't need the complete title, just a few key words eg title=Pride, Prejudice
browseNode   Positive integer browse nodes are positive integers that identify product categories, for example, Literature & Fiction: (17), Medicine: (13996), Mystery & Thrillers: (18), Nonfiction: (53), Outdoors & Nature: (290060). You can find more about browse nodes here.
maxresults 10 number from 1 to 10 this parameter controls the number of results displayed for an item search, note that Amazon will always return a maximum of 10, for results beyond the first 10 use the itemPage parameter
itemPage 1 number from 1 to 10 (1 to 5 if searchIndex = All) use to display results beyond the first 10, eg itemPage=2 displays the second 10 results. There is no way to display beyond the first 100 results, Amazon suggest in that case to refine your search
sort relevance 'price' (low to high), '-price' (high to low), 'salesrank', 'titlerank' (Alphabetical: A to Z), '-titlerank' (Alphabetical: Z to A) and many others control the sort order of results using the sort option, which can take many values, depending on the search index and your locale. You can see the complete list here. Eg: sort=-price
useAccordion no yes, no Use a collapsible accordion to display results, to save space on the page
modalReviews no yes, no have the customer reviews display in a modal window when you click a link, rather than in an iframe on your page
articleLayout article article, blog, search, book, brand, or custom layout name control the layout when an an item lookup is viewed in a Joomla article view. Note that you can create your own custom layout, it you put it in the plugin tmpl folder you can then specify the layout using this parameter, eg if your custom layout is called dvd, use articleLayout=dvd
blogLayout article article, blog, search, book, brand, or custom layout name control the layout when an an item lookup is viewed in a Joomla blog view, as for the article view, you can set your own custom layout, eg if your custom layout is called dvd, use blogLayout=dvd
searchLayout search article, blog, search, book, brand, or custom layout name control the layout of item search results, eg searchLayout=dvd
mode   simple use this to override the plugin behaviour, if the plugin is using the shopping cart mode on your site, but you want to override this and have just a simple link to the Amazon site for your product, then put mode=simple in your short code
linkType   internal, external use this setting to force product links to point to a product page on your site (internal) or directly to the Amazon site (external)
trackingId     use this setting to supply a tracking id which will be used in the affiliate code to track conversions from specific links - you create tracking ids in your Amazon associates dashboard

You don't have to specify all the parameters, any that you omit will take the default values set in the plugin configuration, or the default value listed above.

Controlling the Results Page

By default, Amazon returns the first page of results, containing up to 10 results. You can change this using the itemPage option, which  can take a value from 1 to 10, and is used with search operations to determine which page of results are displayed. If you select a value over 10 you will get an error.  Amazon recommend in that case that you refine your search to return fewer results.

Controlling the Sort Order

You can control the sort order of results using the sort option, which can take many values, depending on the search index and your locale. The default is 'relevance', which depends on how often the keywords turn up in the item description. If you leave the sort option blank this is the ordering which will be used, which will normally be a good choice. Other popular ones that are defined in most cases are 'price' (low to high), '-price' (high to low), 'salesrank', 'titlerank' (Alphabetical: A to Z), '-titlerank' (Alphabetical: Z to A).

You can see the complete list here:

Associates IDs for Authors

Amazon will not allow the use of more than one associates account (per country) on your site, so you cannot allow your authors to use their associates id (this was possible in the past, which is why there is a legacy setting for this). If you want to track sales from individual authors you will need to create a tracking id for them in your associates account, then supply this tracking id in the short code in place of the associates id. For example


for legacy reasons this short code can also be used:-


It will be treated in exactly the same way, that is, as a tracking id.


The Amazon product advertising API is available for the following countries: USA, Canada, UK, France, Germany, Italy, Japan, China, India, Spain, Brazil and Mexico. The plugin can support all these. Normally you would set the country in the plugin manager options, but, if you want to display products from more than one country website you can include this as a parameter in the embedding code. Country can take the values

  • com
  • de
  • fr
  • ca
  • cn
  • it
  • in
  • es


By default the plugin will cache the results that it fetches from the Amazon server, with a default caching time of 30s. If you want to turn this off then you can set it to a negative number. You can also clear the cache in the AmazonWS API system plugin options.

However for a production site you are strongly encouraged to keep the caching turned on. The advantage of caching is that it will speed your page loading time, and it will avoid problems with Amazon's 'fair use' policy. They restrict the number of requests that they will respond to, approximately one per second per site. They allow some flexibilty, but if you find that you are no longer getting any results, or only intermittently getting them, then this is the likely explanation, so you are recommended to turn on caching. Amazon do prefer that you keep the cache time short, so that prices do not change.

The plugin will automatically manage the cache, so that old results that lie outside the cache time will be deleted, so you do not have to worry about clearing it.

More about caching here:


You can select differing layouts for whether the plugin output is viewed in an article displayed in Joomla article or blog layout. You can set these using the plugin articleLayout and blogLayout options, which can be set either in the plugin manager or using the plugin embedding code.

You can also define your own layouts, simply by adding your own file to the amazonWS/tmpl folder, it will be automatically detected by the plugin. The easiest way to do this is to make a copy of an existing template, just give it a new name, edit it, then upload it to the folder. If you are creating a new template from scratch remember to give the file a .php extension or it will not be recognized, also remember to include at the beginning of the file the line

<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>

This prevents the file from being directly accessed by an attacker.

Once you have set up your new layout you should see it listed in the plugin article and blog layout options. You can also specify it inline. For example suppose you have created a new template called music.php, you can then use the embedding code


Note that you do not include the .php extension in the embedding code. You do not need to include both the articleLayout and blogLayout options, if one is not included the value will be taken from the plugin options set in the plugin manager. For example you might want to have a standard layout for when the article is viewed in blog layout, consisting of just the product title and price and a thumbnail image, so you would set this in the plugin manager, then just specify the articleLayout in the embedding code.




Donate to Us

If you like our extensions, consider making a donation to say thanks.


Support Forum