NAME

Net::Amazon::RemoteCart - Perl extension for dealing with Amazon.com's remote shopping cart API

SYNOPSIS

    use Net::Amazon::RemoteCart;

    # Start a new cart
    my $cart = Net::Amazon::RemoteCart->new
        ( token =>'my_amazon_developer_token' ,
         affiliate_id =>'my_amazon_assoc_id', 
         );

    # Add some stuff
    my $res = $cart->add( 'myasin' =>1, 'myotherasin'=>4 );

    # See if our request succeeded
    unless ($res->status == 1){
        print "Problem with Amazon request: ", $res->message, "\n";
    }


    # Get data for all cart items
    my $arrayref_of_item_data = $cart->get_items();

    # Get info for a single item based on its ASIN
    my $item = $cart->get_item('myasin');

    # Get the total cost of the items in the cart
    my $total = $cart->total_cost();

    # Maybe save the cart in a session object like CGI::Session
    $session->param("cart", $cart);


    # A later request...

    # Recreate the cart from the one saved in session
    %cart_params = %{ $session->param("cart") };
    my $cart = Net::Amazon::RemoteCart->new(%cart_params);

    # Or instead...
    my $cart = Net::Amazon::RemoteCart->new
        ( token =>my_amazon_developer_token ,
         affiliate_id =>my_amazon_assoc_id,
         cart_id =>mycart_id,
         hmac =>mycart_hmac,
         );
    # update local cart instance by fetching from Amazon
    $res = $cart->sync();


    # Modify quantities
    my $res = $cart->modify('myasin' =>2, 'myotherasin'=>1 );

    # Remove items
    $res = $cart->remove('myasin1', 'myasin2');

    # Get a list similar products (ASINS)
    $arrayref_of_asins = $cart->similar_products();

    # Get the URL for transferring the user and cart
    # over to Amazon for checkout
    $url_string = $cart->purchase_url();


    

DESCRIPTION

Net::Amazon::RemoteCart,

RemoteCart is an interface to Amazon Web Services Remote Cart API, built on Mike Schilli's Net::Amazon package.

RemoteCart attempts to be a consistent and easy to use interface to the Amazon remote cart API. I've tried to make it work as closely as is practical to how someone (Ok, by someone I mean ME) would expect a shopping cart to work. It has methods to add, remove, fetch items, and modify their quantities based on the product's ASIN.

Each time a request goes to Amazon's remote cart (i.e. for adding, modifying, removing items, or running sync(), etc.), AWS returns the data for the whole cart. So the RemoteCart module will update it's own representation of the cart each time this happens. Then when you access methods like get_items() or purchase_url(), the data is retrieved from the local instance of the cart rather than accessing Amazon's server every time.

One thing it doesn't do for you is maintain state between requests. This can be done either by saving the cart object in a session and passing that to new() on the next request, or by saving just the cart_id and hmac (returned from Amazon) and passing those to new() and then running sync() or get_items_online() to refetch the cart data.

I've also added a couple of convenience methods like total_cost(), and formatted versions of the prices that I think are useful but not provided from Amazon's end.

METHODS

new()

Create a new cart instance. Requires that an Amazon developer token and an Amazon affiliate ID be passed in. See Amazon's Web Services page for more info. If you don't yet have an affiliate ID, you can use "webservices-20" for testing.

    $cart = Net::Amazon::RemoteCart->new
        ( token =>my_amazon_developer_token,
         affiliate_id =>my_amazon_assoc_id, 
         );
sync()

Synchronize the local cart's data with Amazon's remote cart data.

Requires that cart_id and hmac be set in the RemoteCart obj or be passed to this method. If items have been added to the current cart instance, then the cart_id and hmac will already be set.

    $res = $cart->sync();

or

    $res = $cart->sync(cart_id=>'my_cart_id', hmac=>'my_cart_hmac');
add()

Add one or more items to the remote cart.

Does NOT require that cart_id and hmac be set. If they are not set, a new remote cart will be created.

If an item or items that are already in the current cart instance are re-added, a separate "modify" request will be generated for those items.

Running $cart->sync before adding items to an existing remote cart would be a good idea if you're not sure that you have the latest data in your current cart instance. Otherwise you can end up with multiple versions of the same item in your remote cart, making it difficult to remove or modify them.

    $res = $cart->add('asin'=>quantity, 'anotherasin'=>itsquantity);
modify()

Modify the quantity of items in the remote cart.

Requires that cart_id and hmac be set.

If the quantity is set to 0 for one or more items, a separate "remove" request will be generated for those items. If an item isn't set in the current cart instance, it will be skipped. Running $cart->sync before modifying would be a good idea if you're not sure that you have the latest data set in your cart instance.

    $res = $cart->modify('asin'=>newquantity, 'anotherasin'=>itsnewquantity);
remove()

Remove items from the remote cart.

Requires that cart_id and hmac be set. If items have been added to the current cart object, then the cart_id and hmac will already be set.

    $res = $cart->remove('asin1', 'asin2', 'anotherasin');
clear()

Clear all items from the remote cart.

Requires that cart_id and hmac be set. If items have been added to the current cart object, then the cart_id and hmac will already be set.

    $res = $cart->clear();
get_items()

Fetch a list of the items in the cart. This gets the item data from the local current instance of the cart. To get the item list remotely from Amazon, see get_items_online

    $hashref_of_items = $cart->get_items();
get_items_online()

Fetch a list of the items in the cart from Amazon. This gets the item data remotely from Amazon. To get the item list from the local instance of the cart, see get_items

    $hashref_of_items = $cart->get_items_online();
get_item()

Fetch data for an individual item in the cart based on ASIN. This gets the item data from the local current instance of the cart. To get the item list remotely from Amazon, run $cart->sync() first.

    $hashref_of_item_data = $cart->get_item('myasin');

Here's a Data::Dumper dump of a typical item as returned by get_item() or in the list from get_items():

       {
          'asin' => 'B000005QQQ',
          'quantity' => 3,
          'merchant_sku' => undef,
          'list_price' => 'USD 24',
          'list_price_fmt' => '$24.00',
          'our_price' => 'USD 9.6',
          'our_price_fmt' => '$9.60',
          'product_name' => 'Ginsu Knife',
          'item_id' => '9472289293564101475'
        };
total_cost()

Returns the total cost of the items in the cart. Uses Amazon's currency formatting, i.e "USD" or "JPY". It will, correct weirdness with Amazon's decimal places, so you won't get values like "USD 45.2". If you want the currency to be an HTML entity, use total_cost_fmt().

    $str = $cart->total_cost();
total_cost_fmt()

Returns the total cost of the items in the cart with the currency as an HTML compatible symbol (i.e. $ for USD or &yen for JPY).

    $str = $cart->total_cost_fmt();
hmac()

Get or set the hmac

cart_id()

Get or set the cart_id

purchase_url()

Get the purchase URL for sending the user to Amazon's checkout. Accessing this URL will delete the remote cart from Amazon's system.

similar_products()

Get a list of products similar to those in the cart

SEE ALSO

Net::Amazon

For more info on Amazon Web Services, see:

http://www.amazon.com/gp/browse.html/ref=sws_aws_/002-2831321-1001669?node=3435361

INSTALLATION

This module requires the Net::Amazon package, which in turn requires Log::Log4perl, LWP::UserAgent, and XML::Simple 2.x

Once all dependencies have been resolved, "Net::Amazon::RemoteCart" installs with the typical sequence

    perl Makefile.PL
    make
    make test
    make install

LIVE TESTING

(This works the same as for the main Net::Amazon package) Results returned by Amazon can be incomplete or simply wrong at times, due to their "best effort" design of the service. This is why the test suite that comes with this module has been changed to perform its test cases against canned data. If you want to perform the tests against the live Amazon servers instead, just set the environment variable

    NET_AMAZON_LIVE_TESTS=1

CONTACT

For questions about Net::amazon in general, the The "Net::Amazon" project's home page is hosted on

    http://net-amazon.sourceforge.net

where you can find documentation, news and the latest development and stable releases for download. If you have questions about how to use "Net::Amazon", want to report a bug or just participate in its development, please send a message to the mailing list at

    net-amazon-devel@lists.sourceforge.net

For question, comments, suggestions regarding RemoteCart.pm please send to either the Net-Amazon mailing list or directly to the author (see below).

AUTHOR

David Emery, <demery@skiddlydee.com>

Thanks to Mike Schilli for helpful comments and advice. Parts of the RemoteCart.pm docs were copied from Net::Amazon.

COPYRIGHT AND LICENSE

Copyright 2004 by David Emery

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.