API Overview
Once the API is added to your store (it is in version 4.0+ by default) and enabled (see below) you can access the API via:

http://www.yourstore.com/api/

All API requests are to be done by POST, and the return value is a serialized PHP array.

The specific api function and any variables are to be included in the POST by your application.

Enabling the API
When you install your store the API is disabled by default. To enable the API simply login to your freshadmin area and go to “Tools -> Configure the API”.

Follow the instructions here to enable the API and get your access details (Key and Secret Key).

Common POST Variables

The following variables are required to be sent via POST each time you access the API.

apikey – Your unique apikey
hash – a hash generated using your secret key and a timestamp (see below)
timestamp – the same one used to generate the hash
function – the api function you want to call

Each specific API function may need additional post variables (e.g. a product id)

Security and API Authentication
Each store has a unique API Key and a Secret Key. These are found in the freshadmin area and can be regenerated.

The API also can be enabled or disabled via freshadmin (it is disabled by default).

Each API request needs the API Key and a hash generated using the Secret Key and a timestamp. The timestamp also needs to be sent with the request.

On the store, the timestamp and secret key are also used to generate a hash. If the two hashes match, security is passed.

The PHP function for generating the hash is md5().

See the file apitester.php included with your store for example uses of the API and code for generating the hash.

Output From the API
The output will be a PHP serialized array. To get an array of the output, just use the php function unserialize().

Errors Reported from the API
If there is an error in passing security or with a specific function, the following will be returned only:

status – will be set to “Error”
errormessage – will contain the specific error message

API Functions

Test Authentication
Description: A function for testing the API Key and Secret Key
Function: testauthenatication
Parameters:
Returns:
authenticationvalid (boolean) – true if authentication passes

Get Category List
Description: Gets the entire category tree for the store
Function: getcategorylist
Parameters:
Returns:
categorylist (array) – The category tree

Get Best Sellers
Description: Gets the current best selling products
Function: getbestsellers
Parameters:
qty (int) – Quantity of products (required)
Returns:
bestsellers (array) – Array of products

Get Special Offers
Description: Gets the current special offers
Function: getspecialoffers
Parameters:
qty (int) – Quantity of products (required)
Returns:
specialoffers (array) – Array of products

Get Product
Description: Gets a single product. Can be used with either a product_id or asin
Function: getproduct
Parameters:
product_id (int) – The unique id for the product
asin (string) – The amazon unique id for the product
Returns:
product (array) – The entire product

Get Cart
Description: Gets the current cart contents and other details. Both hmac and cart_id are required, and they can be found in the $_COOKIE for any visitor who has an active cart.
Function: getcart
Parameters:
hmac (string) – The HMAC identifier for the cart (required)
cart_id (string) – The cart_id indentifier for the cart (required)
Returns:
cart (array) – The full cart contents and details