The Checkout by Amazon Shopping Cart Guide

A reference guide for merchants and developers who want to use the Checkout by Amazon Shopping Cart on their site

 2009-11 Amazon.com, Inc. or its Affiliates

Table of Contents
1 Overview of the Checkout by Amazon Shopping Cart ......................................................................1 1.1 Your Tasks When Integrating with the Checkout by Amazon Shopping Cart .............................. 2 1.2 Other Documentation.................................................................................................................. 2 1.3 Whats New in This Document .................................................................................................... 3 Enable the Checkout by Amazon Shopping Cart Functionality ....................................................... 4 Add a Navigation Link to Display the Shopping Cart ........................................................................ 5 Use CSS Attributes to Integrate Add to Cart Buttons ...................................................................... 8 4.1.1 Add cart attributes at the HTML page level ........................................................................... 8 4.1.2 Add the item attributes using HTML tags ............................................................................ 10 Modify Your Shopping Cart Security Settings ................................................................................. 13 Optional Features of the Shopping Cart........................................................................................... 15 6.1 Modify the Appearance of Your Shopping Cart Pop-up Window ............................................15 6.2 Show the Current Number of Items and Their Cost in the Navigation Link ........................... 16 6.3 Add or Display Custom Attributes ............................................................................................ 19 6.3.1 Data attributes ....................................................................................................................... 19 6.3.2 Display attributes ............................................................................................................... 20 6.4 Set Item Expiration Dates .......................................................................................................... 20 Merchant Configuration Options ...................................................................................................... 21 7.1 Toggle the Debug Mode ............................................................................................................. 21 7.2 Toggle the Display of the Shopping Cart When an Item Is Added to the Cart ....................... 22 7.3 Set a Continue Shopping URL ................................................................................................... 22 Frequently Asked Questions about the Checkout by Amazon Shopping Cart ............................. 23 8.1.1 What is the Checkout by Amazon Shopping Cart? ............................................................... 23 8.1.2 How do I enable the Checkout by Amazon Shopping Cart on my existing website that uses Checkout by Amazon buttons? ................................................................................................. 23 8.1.3 Can I set my own custom text or image for the shopping cart clickable area? .................. 23 8.1.4 What are CSS attributes and how do I use them? ................................................................ 24 8.1.5 How do I enable the display of the shopping cart? .............................................................. 24 8.1.6 How do I enable the display cost of the total items in the shopping cart? ........................ 24 8.1.7 How do I enable the display of the subtotal of the items in the shopping cart? ............... 24 8.1.8 Must I manually convert my Checkout with Amazon buttons to Add to Cart buttons? .... 25 8.1.9 Can I set custom attributes such as size or color?................................................................ 25 8.1.10 Can I set custom display attributes? ................................................................................. 25 8.1.11 Can I set an expiration date for a product in the shopping cart? .................................... 26 8.1.12 Can I toggle a debug mode to verify my carts functionality? ......................................... 26 8.1.13 Can I automatically show or hide the shopping cart window when my customer adds any item to the cart? .......................................................................................................................... 26 8.1.14 Can I send customers to a URL after they complete a purchase? ................................... 27 8.1.15 Can I use the Cart Up-sell feature with the Checkout by Amazon Shopping Cart? ........ 27 8.1.16 Can I use callbacks with the Checkout by Amazon Shopping Cart? ................................ 27 8.1.17 Can I use instant order processing notifications with the Checkout by Amazon Shopping Cart? ................................................................................................................................... 27 8.1.18 Can I use Fulfillment by Amazon with the Checkout by Amazon Shopping Cart?.......... 27 8.1.19 Can I make Flash content display behind the Checkout by Amazon Shopping Cart? .... 27

2 3 4

5 6

ii

The Checkout by Amazon Shopping Cart Guide 8.1.20 Will purchases made using the Checkout by Amazon Shopping Cart automatically decrement my inventory?.................................................................................................................. 27 9 Appendix A: The Checkout by Amazon Shopping Cart CSS Tags .................................................. 28 10 Appendix B: Supported HTML Tags for a CSS-based Shopping Cart ............................................ 30 11 Appendix C: Using XML- or HTML-based Integration Methods to Build a Shopping Cart............ 31 11.1 Chose a Method for Creating an Add to Cart Button ...............................................................31 11.2 How the Shopping Cart Works with Checkout by Amazon Buttons........................................31 12 Appendix D: Merchant Configuration Options for XML- or HTML-based Carts ........................... 34 12.1 Set Shopping Cart Options with XML-based Carts................................................................... 34 12.1.1 Custom data attributes ...................................................................................................... 34 12.1.2 Display attributes ............................................................................................................... 34 12.1.3 Item expiration date .......................................................................................................... 35 12.2 Set Shopping Cart Options with HTML-based Carts ................................................................ 35 12.2.1 Custom data attributes ...................................................................................................... 35 12.2.2 Display attributes ............................................................................................................... 36 12.2.3 Item expiration date .......................................................................................................... 36 13 Appendix E: The Checkout by Amazon Shopping Cart Schema Definitions ................................. 37

iii

The Checkout by Amazon Shopping Cart Guide

Overview of the Checkout by Amazon Shopping Cart

A shopping cart enables your customers to buy multiple products at the same time. Shopping carts can reduce friction and increase total purchase volume on your website. This illustration shows how the Checkout by Amazon Shopping Cart works. First, your customers click the Add to Cart button to add the products to the shopping cart:

Then, when your customers are ready to checkout, they click the View Cart area (or a similarly named area) to see the shopping cart in a pop-up window and then start the checkout process:

 2009-11 Amazon.com, Inc. or its Affiliates You customers can simply click the Continue Checkout button or Buy Now with 1-Click button to go through the remaining steps to place the order, or click Continue Shopping to add more products to their order. To view more about the Checkout by Amazon Shopping Cart, please see our online Shopping Cart page at the Amazon Payments website.

1.1

Your Tasks When Integrating with the Checkout by Amazon Shopping Cart

The Checkout by Amazon Shopping Cart is a feature of Checkout by Amazon. If you have not already signed up for a Checkout by Amazon seller account, please go here to sign up. Once youve signed up for Checkout by Amazon, you have four tasks to integrate with the Checkout by Amazon Shopping Cart: 1. Enable the Checkout by Amazon Shopping Cart functionalityyou enable the Checkout by Amazon Shopping Cart by adding JavaScript entries to your webpage. See Step 1: Enable the Checkout by Amazon Shopping Cart Functionality for more details. 2. Add a navigation link to display the shopping cartyou enable the appearance of the popup shopping cart by adding <div> entries to your webpage with specific class values. See Step 2: Add a Navigation Link to Display the Shopping Cart for more details. 3. Create Add to Cart buttonsyou use CSS attributes added as specific class values to create your buttons. See Step 3: Use CSS Attributes to Integrate Add to Cart Buttons for more details. 4. Change Your Shopping Cart Security Settingsyou modify the security settings used by Seller Central to accept unsigned carts. See Step 4: Modify Your Shopping Cart Security Settings for more details. The rest of this document discusses how to accomplish these tasks.

1.2

Other Documentation
Audience, Purpose, and Goals For merchants who want to use a simple, step-by-step approach in setting up Checkout by Amazon on their websites. The Getting Started Guide walks merchants through the process, from gathering the required information for signing up for an account to setting up a button on their websites. For merchants and developers who want a detailed list of ways to integrate their website with Checkout by Amazon. The Implementation Guide provides the information needed for programming and code development. Note that there are three versions of this document: one for those who just want to paste the button code built using the Create Checkout Button feature in Seller Central, one for HTML-based code, and one for XML-based code.

You can read our downloadable files (PDF) to understand more about Checkout by Amazon. Resource Getting Started Guide (PDF)

Standard Checkout Button Creation Wizard Implementation Guide (PDF) Standard Checkout HTML Implementation Guide (PDF) 2

The Checkout by Amazon Shopping Cart Guide Resource Standard Checkout XML Implementation Guide Using Seller Central (PDF) Best Practices Guide (PDF) Launch Checklist (PDF) Launch Checklist (XLS) Callback API Guide (PDF) Audience, Purpose, and Goals

For merchants who want an overview of Seller Central. Contains the best tips for merchants who want to set up their websites to use Amazon Payments, with advice for planning, setting up, and dayto-day operations. For merchants and developers planning to set up and use Checkout by Amazon on their site.

For developers who want to build their own applications to calculate shipping and tax rates as well as promotional discounts and then send these results to Checkout by Amazon. Callback API Guide (PDF) For developers who are using the XMLNS with a date of 2008-11-30 and who want to build their own applications to calculate shipping and tax rates as well as promotional discounts and then send these results to Checkout by Amazon. Developer Cheat Sheet For developers who want a quick, 1-page summary of how to enable for the Callback API (PDF) callbacks. Instant Order Processing For developers who want to automate order notifications with Amazon Notifications API Guide Payments. (PDF) Using Custom Data Fields For merchants and developers who want to include custom data fields in (PDF) their carts. The Checkout by Amazon For merchants and developers who want to use the Checkout by Amazon Shopping Cart Guide Shopping Cart on their site. (PDF) Using Checkout by For developers interested in Checkout by Amazon as an alternate Amazon as a Payment payment method on their site. Option (PDF) Open-Source Shopping For developers interested in open-source carts that support Checkout by Cart Solutions (PDF) Amazon (currently osCommerce 1.x and Zen Cart). osCommerce Installation For developers interested in the osCommerce open source cart, v. 2.0 and Configuration Guide and greater. (PDF)

1.3
Ver 1.4

Whats New in This Document

Date 2011-08-12 Changes Updated FAQ response about using item_sku field and item_fulfillment_network field . Updated item_sku definition to include example of item_sku field requirements Added a link to the Shopping Cart page on the Amazon Payments site. Initial Release

1.3 1.0

2011-07-14 2009-05-27

 2009-11 Amazon.com, Inc. or its Affiliates

Enable the Checkout by Amazon Shopping Cart Functionality

The first step to enable the pop-up shopping cart window is to add several <script> entries to the head section of your webpage. To enable the shopping cart functionality, simply add the following lines of code to the head section:
<script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/jquery.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script>

For example, suppose the head section of your webpage looks like this:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> <title>Widjii Fish</title> <script language="javascript" src="/scripts/home.js"></script> </head> <body> ...

You modify this section to add the following lines of code:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> <title>Widjii Fish</title> <script language="javascript" src="/scripts/home.js"></script> <script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/jquery.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script> </head> <body> ...

Nothing happens yet; these script lines simply enable the functionality. You still must add the <div> tags to your code to display the Checkout by Amazon Shopping Cart features.

The Checkout by Amazon Shopping Cart Guide

Add a Navigation Link to Display the Shopping Cart

Next, you add two <div> tags (one nested in the other) in the website navigation areas of your webpage (where you want to show a View Cart clickable area). The outer <div> mark has the class value of amazonPaymentsCart; the inner <div> has a class value of amazonPaymentsCart_Header. If you want to use your own text or graphic for this link, you simply wrap your text or graphic with these <div> entries. If you leave the content of these <div> entries blank, then the link appears as with the default text Your Shopping Cart.

Suppose your rendered page looks like this:

And suppose you use the following code to display your heading and navigation section of your webpage (the ellipses dots represent code weve snipped out to make this example clearer):
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> ... </head> <body> <!-- This is the navigation and branding area of the webpage --> <table> <tr> <td colspan="2"><img src="Logo.png" alt="" /></td> </tr> <tr> <td></td> <td width="450">

 2009-11 Amazon.com, Inc. or its Affiliates

<b>View Cart</b> </td> </tr> <tr> <td colspan="2"><td> </tr> </table> <!-- code to display items--> ...

To enable this for the shopping cart, you add the <div> entry with the class values as shown below:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> ... </head> <body> <!-- This is the navigation and branding area of the webpage --> <table> <tr> <td colspan="2"><img src="Logo.png" alt="" /></td> </tr> <tr> <td></td> <td width="450"> <div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"> <b>View Cart</b> </div> </div> </td> </tr> <tr> <td colspan="2"><td> </tr> </table> <!-- code to display items--> ...

The Checkout by Amazon Shopping Cart Guide When you are done, your webpage with its shopping cart will look like this:

Notes The shopping cart navigation link <div> named amazonPaymentsCart_Header has a value, <b>View Cart</b> If you leave this <div> empty, then the navigation link will appears as Your Shopping Cart. You can modify the colors used to display the cart by going to Seller Central, clicking the Settings tab, and then clicking the Shopping Cart Settings link. See Modify the Appearance of Your Shopping Cart Pop-up Window, below, for more information.

 2009-11 Amazon.com, Inc. or its Affiliates

Use CSS Attributes to Integrate Add to Cart Buttons

After youve entered your global parameters and set up your navigation link area, you use CSS (Cascading Style Sheet) attributes to add or enable the Add to Cart buttons for your products. (CSS attributes are sometimes called CSS Annotations.) When your customers view the resulting webpage, HTML tags you modify with the necessary CSS attributes enable a clickable Add to Cart button. Then, when customers click the Your Shopping Cart navigation link, the shopping cart pop-up window appears, displaying the items in the cart and enabling the customers to continue checkout. Note If you use CSS attributes, you should use Seller Central to set up the shipping rates, tax rates, and promotional discounts you want to use when calculating your shopping cart totals. See the Checkout by Amazon Getting Started Guide (PDF) for more information about how to set up and use Seller Central. To enable the products on your web page for the Checkout by Amazon Shopping Cart, you follow these steps: 1. Add cart attributes at the HTML page level. 2. Add the item attributes using HTML tags. This lets you build a webpage of clickable items supported by the Checkout by Amazon Shopping Cart. 4.1.1 Add cart attributes at the HTML page level Before you add your items to the page, you add a set of entries for values common to all items in the cart such as currency type or your Merchant ID. These values are necessary to process the order. You put these common values in a <div> with the id of global_parameters as shown in this code sample:
<div id="globalParameters"> <input name="weight_unit" value="lb" type="hidden" /> <input name="currency_code" value="USD" type="hidden" /> <input name="merchant_id" value="AEIOU1234AEIOU" type="hidden" /> </div>

You can add this <div> section above or below the section where you have your button code; its easiest just to make the global_parameters the first set of entries after the <body> tag. For a complete list of parameters you can use for your common values, see Appendix A: The Checkout by Amazon Shopping CSS Tags. 8

The Checkout by Amazon Shopping Cart Guide Notes A webpage using CSS attributes to build Add to Cart buttons must have a globalParameters section with the entry for your merchant_id. To retrieve your merchant_id, go to Seller Central, click the Settings tab, and then click Checkout Pipeline Settingsthe Merchant ID appears on the page next to Merchant ID as an alphanumeric string similar to AEIOU1234AEIOU. Here is an example of a webpage using CSS attributes to enable buying several items. Note that the webpage already contains the <script> entries (mentioned earlier in Step 1: Enable the Checkout by Amazon Shopping Cart Functionality):
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> <title>Widjii Fish</title> <script language="javascript" src="/scripts/home.js"></script> <script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/jquery.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script> </head> <body> <!-- Page level attributes/ global parameters --> <div id="globalParameters"> <input name="weight_unit" value="lb" type="hidden" /> <input name="currency_code" value="USD" type="hidden" /> <input name="merchant_id" value="AEIOU1234AEIOU" type="hidden" /> </div> <!-- This is the navigation and branding area of the webpage --> <table> <tr> <td colspan="2"><img src="Logo.png" alt="" /></td> </tr> <tr> <td></td> <td width="450"> <div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"> <b>View Cart</b> </div> </div> </td> </tr> <tr> <td colspan="2"><td> </tr> </table> <!-- This is product-display area of the webpage --> <table> ...

 2009-11 Amazon.com, Inc. or its Affiliates

</table> </body> </html>

4.1.2 Add the item attributes using HTML tags Now add HTML tags such as <table>, <div>, <span>, <td>, or <input> with CSS attributes to enable the display of the item information. See Appendix B: Supported HTML Tags for a CSSbased Shopping Cart for a list of the tags you can use. Suppose, for example, you want to display the following products:

Heres a sample of what the code might look like to sell these items:
<table class="item"> <tr> <td> <img class="item_image_url" src="http://img/6TL2G.jpg"/> <span class="item_title">Red Fish</span> &nbsp; $ <span class="item_price">19.99</span> <input class="item_description" value="A red fish packed in spring water." type="hidden" /> <input type="text" class="item_quantity" value="1"/> <input type="button" value="Add Item" class="add_item"> </td> </tr> </table > <table class="item"> <tr> <td> <img class="item_image_url" src="http://img/8MP9Q.jpg"/> <span class="item_title">Blue Fish"</span> &nbsp; $

10

The Checkout by Amazon Shopping Cart Guide

<span class="item_price">49.99</span> <input class="item_description" value="A blue fish packed in light olive oil." type="hidden"/> <input type="text" class="item_quantity" value="1"/> <input type="button" value="Add Item" class="add_item"> </td> </tr> </table > ...

Note that each tag includes an attribute class with a specific value. Also note that the breakdown of each item is as follows: An item <table> entry to enclose the item information An image (optional) for the item A <span> entry to display the item title A <span> entry to display the price An <input> value for the item description An <input> value for the item quantity An <input> value for the button text

The basic layout of this content follows this hierarchy: Item (top level) Item image Item title Item price input description input quantity input button That is, the item is the top-level entry, and nested beneath it are the attributes of that item, such as the title or price, along with the inputs that enable the item to be clickableand therefore buyable. You can repeat this basic setup to add clickable entries for each item you want to sell. For a complete list of CSS attributes you can use, see Appendix A: The Checkout by Amazon Shopping Cart CSS Tags. Notes A buyable item created using CSS attributes must include the following CSS attributes added using HTML tags set with the class attributes item, item_title, and item_price. A buyable item must include an input with a type of button, a value similar to Add Item (such as "Add to Cart"), and a class of add_item.

11

 2009-11 Amazon.com, Inc. or its Affiliates A page displaying a buyable item created using CSS attributes must include the global value merchant_id set in a <div> marked with the id globalParameters. When you build a webpage using CSS attributes, be sure you do not use a currency symbol, such as $, when you enter the item_price.

12

The Checkout by Amazon Shopping Cart Guide

Modify Your Shopping Cart Security Settings

By default, Checkout by Amazon requires signed carts. To enable the Checkout by Amazon Shopping Cart using CSS attributes, youll need to turn off this signature-required feature. Follow these steps to change your shopping cart settings: 1. Log in to Seller Central, click the Settings tab, and then click Checkout Pipeline Settings to display the settings page. Note that the Shopping Cart Security setting is Enabled:

2. Click the Edit button underneath the phrase Integrator URL, then click the Accept only digitally signed XML shopping carts check box to clear the check mark:

13

 2009-11 Amazon.com, Inc. or its Affiliates 3. Click the Update button, and note that the Shopping Cart Security setting now shows Disabled:

Thats it! By adding these CSS attributes to your webpage, youre ready to begin accepting orders using Amazon Payments. For more information on setting shipping and tax rates, setting promotional discounts, and managing orders, see the Checkout by Amazon Getting Started Guide (PDF). If you want, you can now modify your code with optional features, as described in the next section.

14

The Checkout by Amazon Shopping Cart Guide

Optional Features of the Shopping Cart

Modify the appearance of your shopping cart pop-up window Show the current number of items and their cost in the shopping cart pop-up window Show custom display attributes in the shopping cart pop-up window Add custom data attributes to your shopping cart data Set an item expiration date Toggle the debug mode

You can modify your Checkout by Amazon Shopping Cart further with these optional features:

The rest of this section explains how to do these tasks.

6.1

Modify the Appearance of Your Shopping Cart Pop-up Window

You can change the colors used in the shopping cart pop-up window by modifying the settings in Seller Central. To change these values, go to Settings > Checkout Pipeline Settings, click the Shopping Cart Settings link, click the Edit button, and set the values you want:

15

 2009-11 Amazon.com, Inc. or its Affiliates You can set the following values, as shown in this illustration:

1. 2. 3. 4.

Widget body color Scroll window color Widget body text color Scroll window text color

5. Links text color 6. Item price color 7. Subtotal color

6.2 Show the Current Number of Items and Their Cost in the Navigation Link
After you build your webpage that supports the Checkout by Amazon Shopping Cart, you can add optional entries to display the current number of products in the cart along with the total cost of the products in the order. You do this by adding HTML tag with the class of amazonPaymentsCart_TotalItems in your shopping cart section, and HTML tag with the class of amazonPaymentsCart_SubTotal in the shopping cart display section of your webpage. Suppose, for example, you have the following code for your webpage (the ellipses dots represent code weve snipped out to make this example clearer):

16

The Checkout by Amazon Shopping Cart Guide

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> <title>Widjii Fish</title> <script language="javascript" src="/scripts/home.js"></script> <script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/jquery.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script> </head> <body> <!-- This is the navigation and branding area of the webpage --> <table> <tr> <td colspan="2"><img src="Logo.png" alt="" /></td> </tr> <tr> <td></td> <td width="450"> <div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"> <b>View Cart</b> </div> </div> </td> </tr> <tr> <td colspan="2"><td> </tr> </table> <form method=POST ...> <!-- code to display items--> </form> ...

To have the total item count appear on your webpage, you add the following entries to your code (note that the &nbsp; entries are just to put some space between the existing content and the new content in this example):
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> <title>Widjii Fish</title> <script language="javascript" src="/scripts/home.js"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script> <script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/jquery.js" type="text/javascript"></script> </head> <body>

17

 2009 Amazon.com, Inc. or its Affiliates

<!-- This is the navigation and branding area of the webpage --> <table> <tr> <td colspan="2"><img src="Logo.png" alt="" /></td> </tr> <tr> <td></td> <td width="450"> <div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"> <b>View Cart</b> &nbsp;&nbsp;Item(s) <span class="amazonPaymentsCart_TotalItems"></span> &nbsp;&nbsp;Subtotal: $ <span class="amazonPaymentsCart_SubTotal"></span> </div> </div> </td> </tr> <tr> <td colspan="2"><td> </tr> </table> <form method=POST ...> <!-- code to display items--> </form> ...

When you are done, your webpage will look like this:

18

The Checkout by Amazon Shopping Cart Guide

6.3 Add or Display Custom Attributes

Custom attributes let you use arbitrary values at the item level. There are two types of custom attributes: Data attributesinclude more information in the shopping cart data (sent to Amazon Payments) so that you can retrieve the data (such as a motto or style) later in callbacks or instant order processing notifications Display attributesinclude more information in the shopping cart window

6.3.1 Data attributes To add the Data attribute (that is, an attribute thats not already defined in the list in Appendix A: The Checkout by Amazon Shopping Cart CSS Tags), you can use the class item_custom_attribute to set a custom attribute value, an attribute name tag of itemAttributeName set to the name you want to display, and an attribute name of value set to the value you want to send as your custom data. For example, the following code will send a custom data attribute PacketSize with a value of Large and the data attribute solution with a value of Light Olive Oil.
<table class="item"> <tr> <td> <div class="item_title">Red Fish</div> <span class="item_price">19.99</span> <input type="text" class="item_custom_attribute" itemAttributeName="PacketSize" value="Large"> <input type="text" class="item_custom_attribute" itemAttributeName="Solution" value="Light Olive Oil"> </div> </td> </tr> </table>

When you receive the data using callbacks or instant order processing notifications, it will look like this:
... <Item> ... <ItemCustomData> <PacketSize>Large</PacketSize> <Solution>Light Olive Oil</Solution> </ItemCustomData> </Item> ...

Note The content of the item_custom_attribute is used for order processing only. It does not appear to the customer during checkout and does not appear in Seller Central. 19

 2009 Amazon.com, Inc. or its Affiliates 6.3.2 Display attributes To add the attribute to a cart using CSS attributes, you add a display attribute with a value of true, a displayName attribute with the value of the text to show in the shopping cart, and a class attribute with name of the display value. If you do not add the displayName attribute, then just the value you specify will appear. Valid attributes for the class attribute appears in Appendix A: The Checkout by Amazon Shopping Cart CSS Tags. To use a custom display value, set the class value to item_custom_attribute; use itemAttributeName for the name; and use value for the actual text to display. For example, the following code will show a display value of Weight with the item weight of 4 pounds, and a Blurb of Fresh-pax--from the ocean to your oven in 24 hours:
<table class="item"> <tr> <td> <div class="item_title">Red Fish</div> <span class="item_price">19.99</span> <input type="text" class="item_custom_attribute" itemAttributeName="packing_solution" value="Light Olive Oil"> <span display="true" displayName="Weight" class="item_weight">4</span> <input display="true" class="item_custom_attribute" itemAttributeName="Blurb" value="Fresh-pax--from the ocean to your oven in 24 hours" type="hidden"> </div> </td> </tr> </table>

6.4 Set Item Expiration Dates

You can use the ItemExpirationDate attribute to set an expiration date for an item in the cart so that it is not buyable after a set time. To set the expiration date, you add an input entry and then set its type to hidden, its class to item_expiration_date, and its value to the expiration date you want to use, in UTC format. For example, the following code sets the expiration date of the item in the cart so it is not buyable after Oct 31, 2010, at 2:00 pm Pacific time:
<table class="item"> </td> </tr> <div class="item_title">Red Fish</div> <span class="item_price">19.99</span> <input class="item_expiration_date" value="2009-10-31:21:00-9:00" type="hidden" /> </div> </td> </tr> </table>

20

The Checkout by Amazon Shopping Cart Guide

Merchant Configuration Options

You can set several options for your shopping cart to configure your shopping cart operation. You can place these configuration options in a <div> with an id value of merchantConfigurations, anywhere you want on the webpage. You can set the following options: Toggle the debug mode Toggle the display of the shopping cart when an item is added to the cart Set a Continue Shopping URL

7.1

Toggle the Debug Mode

You can use the debug mode to examine the output of the Shopping Cart. To set the state of the debug mode, you add a hidden element with the name debug_mode and a value of true, placed in a <div> with an id value of merchantConfigurations, as shown in the code sample below:
<div id="merchantConfigurations"> <input name="debug_mode" value="true" type="hidden" /> <input name="open_cart_on_add" value="true" type="hidden" /> <input name="continue_shopping_URL" value="http://mydomain.com/continue.html" type="hidden" /> </div>

When you use the debug mode, the output you get will look something like this:
***** Adding Element to Cart ******* [ {name:'item_image_url_1',type:'hidden',value:'http://img/6TL2G.jpg'}, {name:'item_price_1',type:'hidden',value:'19.99'}, {name:'item_quantity_1',type:'hidden',value:'1'}, {name:'item_title_1',type:'hidden',value:'Red Fish'}, {name:'item_custom_attribute_GiftPackColor_1',type:'hidden',value:'Any Color'}, {name:'item_display_attributes_1',type:'hidden',value:'{Gift Pack Color : Any Color}'}, {name:'item_merchant_id_1',type:'hidden',value:'AEIOU1234AEIOU'}, {name:'currency_code',type:'hidden',value:'USD'}, {name:'weight_unit',type:'hidden',value:'lb'}, {name:'tax_rate',type:'hidden',value:'.08'}, {name:'tax_us_state_region',type:'hidden',value:'US_ALL'}, {name:'shipping_method_service_level_1',type:'hidden',value:'standard'}, {name:'shipping_method_price_per_shipment_amount_1',type:'hidden',value:'7.49'}, {name:'shipping_method_price_per_unit_rate_1',type:'hidden',value:'5.00'}, {name:'shipping_method_price_type_1',type:'hidden',value:'weight_based'}, {name:'shipping_method_region_1',type:'hidden',value:'us_full_50_states'}, {name:'cart_promotion_1',type:'hidden',value:'.1'}, {name:'cart_promotion_type_1',type:'hidden',value:'discount_rate'} ]

21

 2009 Amazon.com, Inc. or its Affiliates

7.2

Toggle the Display of the Shopping Cart When an Item Is Added to the Cart

To set the shopping cart display status, you add a hidden element with the name open_cart_on_add with a value of true, placed in a <div> with an id value of merchantConfigurations, as shown in the code sample below:
<div id="merchantConfigurations"> <input name="debug_mode" value="true" type="hidden" /> <input name="open_cart_on_add" value="true" type="hidden" /> <input name="continue_shopping_URL" value="http://mydomain.com/continue.html" type="hidden" /> </div>

When you set this to true, then each time your customer adds an item to the cart, the shopping cart window appears. When you set this to false, then the shopping cart window appears only when your customer clicks the View Shopping Cart area.

7.3

Set a Continue Shopping URL

To set the Continue Shopping URL, you add a hidden element with the name continue_shopping_URL with a value of the page on your website you want to use, placed in a <div> with an id value of merchantConfigurations, as shown in the code sample below:
<div id="merchantConfigurations"> <input name="debug_mode" value="true" type="hidden" /> <input name="open_cart_on_add" value="true" type="hidden" /> <input name="continue_shopping_URL" value="http://mydomain.com/continue.html" type="hidden" /> </div>

Note that the Continue Shopping URL must include the http:// or https:// protocol.

22

The Checkout by Amazon Shopping Cart Guide

Frequently Asked Questions about the Checkout by Amazon Shopping Cart

8.1.1 What is the Checkout by Amazon Shopping Cart? The Checkout by Amazon Shopping Cart enables you to add a shopping cart to your website so that your customers can browse your website, selecting products for purchase, and then paying for all the products at once during checkout. A shopping cart helps customers buy more products, because it reduces the friction of paying for products one at a time. 8.1.2 How do I enable the Checkout by Amazon Shopping Cart on my existing website that uses Checkout by Amazon buttons? Depending on whether you integrate using XML or HTML, you can enable the Checkout by Amazon Shopping Cart with just a few steps 1. Add a few lines of script to the head section of your webpage. 2. Add a <div class="amazonPaymentsCart"><div class="amazonPaymentsCart_Header"></div></div> entry where you want to expose the Checkout link. See Appendix C: Using Checkout by Amazon Buttons to Build a Shopping Cart Solution, below, for more information. 8.1.3 Can I set my own custom text or image for the shopping cart clickable area? Yes. You simply add one entry to the head element & two nested <div> entries: 1. Add a few lines of script to the head section of your webpage. 2. Add a <div class="amazonPaymentsCart"><div class="amazonPaymentsCart_Header"></div></div> entry surrounding your shopping cart code where you want to create a area that, when clicked, will display the shopping cart window. 3. Enter the text you want to use for your clickable area, such as View Cart, or your custom image (using the <img> HTML tag) in the <div> section with the class of amazonPaymentsCart_Header.
<div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"> <img src="/images/header.png" alt="" /> <b>View Cart</b> </div> </div>

Note that if you leave the <div> entries blank (as in the example below), the default text Your Shopping Cart and the default Item total will appear:

23

 2009 Amazon.com, Inc. or its Affiliates

<div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"></div> </div>

8.1.4 What are CSS attributes and how do I use them? CSS attributes (sometimes called CSS Annotations) are entries you add to a webpage with the Checkout by Amazon Shopping Cart that display products for purchase without requiring you to build Checkout buttons. If youre new to Checkout by Amazon, CSS attributes might be the easiest way to build pages with many products for sale, because you dont need to understand much HTML code. See Using CSS Attributes to Build a Shopping Cart, above. 8.1.5 How do I enable the display of the shopping cart? 1. Add a few lines of script to the head section of your webpage. 2. Add a <div class="amazonPaymentsCart"><div class="amazonPaymentsCart_Header"></div></div> entry where you want to expose the Shopping Cart link. See Add a Navigation Link to Display the Shopping Cart for more information. 8.1.6 How do I enable the display cost of the total items in the shopping cart? You enable the default Total Items display by adding an empty <span> (or other HTML tag as listed in Appendix B: Supported HTML Tags for a CSS-based Shopping Cart) with the class value of amazonPaymentsCart_TotalItems to the shopping cart section of your webpage.
<div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"> <b>View Cart</b> &nbsp;&nbsp;Item(s) <span class="amazonPaymentsCart_TotalItems"></span> &nbsp;&nbsp;Subtotal: $ <span class="amazonPaymentsCart_SubTotal"></span> </div> </div>

See Show the Current Number of Items in the Cart and Their Cost for more information. 8.1.7 How do I enable the display of the subtotal of the items in the shopping cart? You enable the default Total Order Cost display by adding an empty <span> (or other HTML tag as listed in Appendix B: Supported HTML Tags for a CSS-based Shopping Cart) with the class value of amazonPaymentsCart_Subtotal to the shopping cart section of your webpage.
<div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"> <b>View Cart</b> &nbsp;&nbsp;Item(s) <span class="amazonPaymentsCart_TotalItems"></span> &nbsp;&nbsp;Subtotal: $ <span class="amazonPaymentsCart_SubTotal"></span> </div> </div>

See Show the Current Number of Items in the Cart and Their Cost for more information. 24

The Checkout by Amazon Shopping Cart Guide 8.1.8 Must I manually convert my Checkout with Amazon buttons to Add to Cart buttons? No. As long as you add the <script> entries to the <head> section of your webpage, the Checkout by Amazon buttons are converted automatically to Add to Cart buttons. 8.1.9 Can I set custom attributes such as size or color? Yes. For example, to add the Data attribute, you can use the class item_custom_attribute to set a custom attribute value, an attribute name tag of itemAttributeName set to the name you want to display, and an attribute name of value set to the value you want to send as your custom data.
<table class="item"> <tr> <td> <div class="item_title">Red Fish</div> <span class="item_price">19.99</span> <input type="text" class="item_custom_attribute" itemAttributeName="PacketSize" value="Large"> <input type="text" class="item_custom_attribute" itemAttributeName="Solution" value="Light Olive Oil"> </div> </td> </tr> </table>

See Adding or Displaying Custom Attributes, above, for more information 8.1.10 Can I set custom display attributes? Yes. For example, to add the attribute to a cart using CSS attributes, you add a display attribute with a value of true, a displayName attribute with the value of the text to show in the shopping cart, and a class attribute with name of the display value. If you do not add the displayName attribute, then just the value you specify will appear. To use a custom display value, set the class value to item_custom_attribute; use itemAttributeName for the name; and use value for the actual text to display.
<table class="item"> <tr> <td> <div class="item_title">Red Fish</div> <span class="item_price">19.99</span> <input type="text" class="item_custom_attribute" itemAttributeName="packing_solution" value="Light Olive Oil"> <span display="true" displayName="Weight" class="item_weight">4</span> <input display="true" class="item_custom_attribute" itemAttributeName="Blurb" value="Fresh-pax--from the ocean to your oven in 24 hours" type="hidden"> </div> </td> </tr> </table>

See Adding or Displaying Custom Attributes, above, for more information.

25

 2009 Amazon.com, Inc. or its Affiliates 8.1.11 Can I set an expiration date for a product in the shopping cart? Yes. You can use the ItemExpirationDate attribute to set an expiration date for an item in the cart so that it is not buyable after a set time.
<table class="item"> </td> </tr> <div class="item_title">Red Fish</div> <span class="item_price">19.99</span> <input class="item_expiration_date" value="2009-10-31:21:00-9:00" type="hidden" /> </div> </td> </tr> </table>

See Setting Item Expiration Dates, above, for more information. 8.1.12 Can I toggle a debug mode to verify my carts functionality? Yes. For example, to set the state of the debug mode, you add a hidden element with the name debug_mode and a value of true, placed in a <div> with an id value of merchantConfigurations.
<div id="merchantConfigurations"> <input name="debug_mode" value="true" type="hidden" /> <input name="open_cart_on_add" value="true" type="hidden" /> <input name="continue_shopping_URL" value="http://mydomain.com/continue.html" type="hidden" /> </div>

See Toggle the Debug Mode, above, for more information. 8.1.13 Can I automatically show or hide the shopping cart window when my customer adds any item to the cart? Yes. For example, to set the shopping cart display status, you add a hidden element with the name open_cart_on_add with a value of true, placed in a <div> with an id value of merchantConfigurations.
<div id="merchantConfigurations"> <input name="debug_mode" value="true" type="hidden" /> <input name="open_cart_on_add" value="true" type="hidden" /> <input name="continue_shopping_URL" value="http://mydomain.com/continue.html" type="hidden" /> </div>

See Toggle the Display of the Shopping Cart When an Item Is Added, above, for more information.

26

The Checkout by Amazon Shopping Cart Guide 8.1.14 Can I send customers to a URL after they complete a purchase? Yes. For example, to set the Continue Shopping URL, you add a hidden element with the name continue_shopping_URL with a value of the page on your website you want to use, placed in a <div> with an id value of merchantConfigurations.
<div id="merchantConfigurations"> <input name="debug_mode" value="true" type="hidden" /> <input name="open_cart_on_add" value="true" type="hidden" /> <input name="continue_shopping_URL" value="http://mydomain.com/continue.html" type="hidden" /> </div>

See Set a Continue Shopping URL, above, for more information. 8.1.15 Can I use the Cart Up-sell feature with the Checkout by Amazon Shopping Cart? Yes, as long as you are building XML-based carts. You cannot use the Cart Up-sell feature in your cart code if you build HTML-based carts. To learn more about the Cart Up-sell feature, please see the section Using the Cart Up-sell Feature in the Integration Guide (PDF). 8.1.16 Can I use callbacks with the Checkout by Amazon Shopping Cart? Yes, as long as you are building XML-based carts. You cannot use the Callback feature in your cart code if you build HTML-based carts. To learn more about the Callback feature, please see the Callback API Guide (PDF). 8.1.17 Can I use instant order processing notifications with the Checkout by Amazon Shopping Cart? Yes. To learn more about the Instant Order Processing Notifications feature, please see the Instant Order Processing Notifications API Guide (PDF). 8.1.18 Can I use Fulfillment by Amazon with the Checkout by Amazon Shopping Cart? Yes. You simply need to be sure that you include the item SKU and item fulfillment network with your other item data. You set the item SKU using the item_sku field and item fulfillment network to AMAZON_NA using the item_fulfillment_network field. 8.1.19 Can I make Flash content display behind the Checkout by Amazon Shopping Cart? Yes. You can set the wmode parameter as transparent in your Flash object code as shown in the code sample below:
<object width="550" height="400"> <param name="movie" value=flashobject.swf"> <embed src="flashobject.swf" width="150" height="20" wmode="transparent"></embed> </object>

8.1.20 Will purchases made using the Checkout by Amazon Shopping Cart automatically decrement my inventory? No. You will need to use the Orders Report (or similar tool) to get your sales and use the information to update your inventory. 27

 2009 Amazon.com, Inc. or its Affiliates

Appendix A: The Checkout by Amazon Shopping Cart CSS Tags

This table lists the CSS attributes (tags) you can use when building a simple shopping cart. For more information about the actual schema definitions, see Appendix A: The Checkout by Amazon Shopping Cart CSS Tags, below. Level Attribute Name
item_category item_condition item_custom_attribute

Notes

When using item_custom_attribute, itemAttributeName must be provided. The value set for item_custom_attribute does not appear during checkout and does not appear in Seller Central.

Item

item_description item_fulfillment_network item_image_url item_is_shipping_taxed item_price item_expiration_date item_promotion item_promotion_type item_quantity item_sku item_tax_rate item_tax_us_state_region item_title item_url item_weight item_weight_unit merchant_signature

Required

Required when using Fulfillment by Amazon.

Required

if signed carts are required, itemlevel and page-level entries must be signed.

Page (common)

currency_code aws_access_key_id integrator_id integrator_name weight_unit shipping_method_service_level shipping_method_price_per_shipment_amount shipping_method_price_per_unit_rate shipping_method_price_type

28

The Checkout by Amazon Shopping Cart Guide Level Attribute Name

shipping_method_region cart_promotion cart_promotion_type tax_rate tax_us_state_region is_shipping_taxed

Notes

Example of an item-level element:

<table class="item"> <!-- item details --> <span class="item_title">Red Fish</span> </table>

Example of a page-level (global) element:

<div id="globalParameters"> <input name="currency_code" value-"USD" type="hidden" /> <input name="merchant_id" value="AEIOU1234AEIOU" type="hidden" /> </div>

For details on what each parameter is and how to use it, please see the section HTML Schema Definitions in the Developer Guide (PDF).

29

 2009 Amazon.com, Inc. or its Affiliates

10 Appendix B: Supported HTML Tags for a CSS-based Shopping Cart

You can use the class tag to modify following HTML elements to specify products that are enabled for the Checkout by Amazon Shopping Cart. The value to use for each HTML element is stated in Description column. HTML Element <img> <input type="radio"> <input type="checkbox"> <input type="file"> <input type="image"> <input> with any other type (for example, hidden, text, password, and so on) <a href> <iframe> <select> <select-one> Description The src attribute of the image. Ignored if src is empty. The value attribute if the radio button is checked. Ignored if not checked. The value attribute if the checkbox is checked. Ignored if not checked. Ignored. The src value. Ignored if type is empty. The value attribute of this element. Ignored if the value is empty.

Value of href. Its value should be a well-formed URL. Ignored. Value of selected option <select class="item_custom_attribute" itemAttributeName="color"> <option value="Red">Red</option> <option value="Blue>Blue</option> </select> The content of the element <div class="item_title"> Calvin and Hobbes Reliquary </div> Content: Calvin and Hobbes Reliquary <div class="item_title"> <b>Coming Up Daisy</b> books and DVD pack </div> Content: <b>Coming Up Daisy</b> books and DVD pack

All Other Elements

30

The Checkout by Amazon Shopping Cart Guide

11 Appendix C: Using XML- or HTML-based Integration Methods to Build a Shopping Cart

If you are already using XML-or HTML-based buttons to integrate with Checkout by Amazon, then you just add the <script> entries and <div> entries (described in Enable the Checkout by Amazon Shopping Cart Functionality and in Add a Navigation Link to Display the Shopping Cart) to your webpage to enable the Checkout by Amazon Shopping Cart. These entries enable the pop-up window to appear on your site showing the products in the cart as well as the total number of products and the order subtotal.

11.1 Chose a Method for Creating an Add to Cart Button

This table can help you choose the best integration method: Your Integration Method Use CSS Attributes to Build a Checkout Solution Benefit Quick, easy way to set up your pages. Skill You set your shipping and tax rates and your promotional discounts in Seller Central. See the Getting Started Guide (PDF) for more information on how to set or change these values. You use your XML or HTML programming skills to create buttons.

Use XML- or HTML-based Integration Methods to Build a Shopping Cart Solution

Continue to integrate using XMLor HTML-based buttons. These buttons allow you to create sophisticated solutions with custom shipping, tax rates, and promotional discounts.

11.2 How the Shopping Cart Works with Checkout by Amazon Buttons
The shopping cart functionality watches to see which buttons are clicked by customers and adds the selected products to the shopping cart. By default, the shopping cart knows about the tags used for XML- or HTML- based carts that use the tag names listed in the Integration Guide (PDF). Suppose, for example, you have the following code to display your heading and navigation section of your webpage (the ellipses dots represent code weve snipped out to make this example clearer):
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> <title>Widjii Fish</title> <script language="javascript" src="/scripts/home.js"></script> </head> <body> <!-- This is the navigation and branding area of the webpage --> <table>

31

 2009 Amazon.com, Inc. or its Affiliates

<tr> <td colspan="2"><img src="Logo.png" alt="" /></td> </tr> <tr> <td></td> <td width="450"> <b>View Cart</b> </td> </tr> <tr> <td colspan="2"><td> </tr> </table> <form method=POST ...> <!-- code to display items--> </form> ...

And suppose your page looks something like this, with Checkout by Amazon buttons used to check items out, one at a time:

You simply modify this webpage to add the following entries to enable the Checkout by Amazon Shopping Cart:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> <title>Widjii Fish</title> <script language="javascript" src="/scripts/home.js"></script> <script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/jquery.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-imagesamazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script>

32

The Checkout by Amazon Shopping Cart Guide

</head> <body> <!-- This is the navigation and branding area of the webpage --> <table> <tr> <td colspan="2"><img src="Logo.png" alt="" /></td> </tr> <tr> <td></td> <td width="450"> <div class="amazonPaymentsCart"> <div class="amazonPaymentsCart_Header"> <b>View Cart</b> </div> </div> </td> </tr> <tr> <td colspan="2"><td> </tr> </table> <form method=POST ...> <!-- code to display items--> </form> ...

The results will look something like this:

Note that the Checkout by Amazon buttons are automatically changed to Add to Cart buttons. Thats it! For more information on order management and next steps to follow, see the Checkout by Amazon Getting Started Guide (PDF).

33

 2009 Amazon.com, Inc. or its Affiliates

12 Appendix D: Merchant Configuration Options for XML- or HTML-based Carts

If you create your own XML-or HTML-based carts using the information provided in the Integration Guide (PDF) and the Developer Guide (PDF) and you are using the Checkout by Amazon Shopping Cart, you set several options in your carts that will affect the display and functionality of the Checkout by Amazon Shopping Cart. You can set the following shopping cart features: Custom Data Attributes Display Attributes Item Expiration Date

For more information about other custom data attributes and how to specify them, please see Using Custom Data Fields Guide (PDF).

12.1 Set Shopping Cart Options with XML-based Carts

If you integrate using XML-based carts, you can set the following options. 12.1.1 Custom data attributes You can set custom data attributes for XML-based carts by following the instructions in the Using Custom Data Fields Guide (PDF). Note You add these custom data attributes to your cart code before you transform it for the <form POST> entries. 12.1.2 Display attributes By default, the Checkout by Amazon Shopping Cart shows the following values in the pop-up window: item_title item_quantity item_image item_price

You can specify and display up to 3 additional values using display attributes. If you specify 4 or more display values, only the first 3 in a list (sorted alphabetically by display name) will appear in the shopping cart window. The xpath for display attributes is /Order/Cart/Items/Item/ItemCustomData/DisplayAttributes. 34

The Checkout by Amazon Shopping Cart Guide To set display attributes for the shopping cart, you use the DisplayAttributes tag containing the values you want to display, as shown in the following code sample:
... <ItemCustomData> <DisplayAttributes> <DisplayAttribute>PacketSize:Large</DisplayAttribute> <DisplayAttribute>Solution:Light Olive Oil</DisplayAttribute> <DisplayAttribute>Guaranteed Fresh</DisplayAttribute> </DisplayAttributes> </ItemCustomData> ...

12.1.3 Item expiration date You can specify an item expiration date for an XML-based cart by adding an ItemExpirationDate entry to the ItemCustomData section of your cart data. The xpath for an item expiration date is /Order/Cart/Items/Item/ItemCustomData/ItemExpirationDate. You add the entry as shown in the code sample below:
<ItemCustomData> <ItemExpirationDate>2009-10-28T10:00:00-9:00</ItemExpirationDate> </ItemCustomData>

12.2 Set Shopping Cart Options with HTML-based Carts

If you integrate using HTML-based carts, you can set the following options. 12.2.1 Custom data attributes You can set custom data attributes for HTML-based carts only at the item level with key-value pairs, as shown in the example below:
<form method=POST action="https://payments.amazon.com/checkout/AEIOU1234AEIOU"> <input name="item_merchant_id_1" value="AEIOU1234AEIOU" type=hidden /> <input name="item_title_1" value="Red Fish" type="hidden" /> <input name="item_price_1" value="19.99" type="hidden" /> <input name="item_quantity_1" value="1" type="hidden" /> <input name="item_1.custom_attribute_1.packetsize" value="Large" type="hidden" /> <input name="item_1.custom_attribute_2.solution" value="Light Olive Oil" type="hidden" /> </form>

When you receive the data using callbacks or instant order processing notifications, it will look like this:
... <Item> ... <ItemCustomData> <Packetsize>Large</Packetsize> <Solution>Light Olive Oil</Solution>

35

 2009 Amazon.com, Inc. or its Affiliates

</ItemCustomData> </Item> ...

12.2.2 Display attributes By default, the Checkout by Amazon Shopping Cart shows the following values in the pop-up window: item_title item_quantity item_image item_price

You can specify and display up to 3 additional values using display attributes. If you specify 4 or more display values, only the first 3 in a sorted list will appear in the shopping cart window. You set the display attributes by setting the name as shown:
<form method=POST action="https://payments.amazon.com/checkout/AEIOU1234AEIOU"> <input name="item_merchant_id_1" value="AEIOU1234AEIOU" type="hidden" /> <input name="item_title_1" value="Red Fish" type="hidden" /> <input name="item_price_1" value="19.99" type="hidden" /> <input name="item_quantity_1" value="1" type="hidden" /> <input name="item_1.display_attribute_1" value="PacketSize:Large" /> <input name="item_1.display_attribute_2" value="Solution:Light Olive Oil" /> <input name="item_1.display_attribute_3" value="Guaranteed Fresh" /> </form>

12.2.3 Item expiration date You can specify an item expiration date for an HTML-based cart by adding an item_expiration_date_n entry to the form used for your button. When the date has passed, the item is removed from the shopping cart without notification in the UI. You add the entry as shown in the code sample below:
<form method=POST action="https://payments.amazon.com/checkout/AEIOU1234AEIOU"> <input name="item_merchant_id_1" value="AEIOU1234AEIOU" type="hidden" /> <input name="item_title_1" value="Red Fish" type="hidden" /> <input name="item_price_1" value="19.99" type="hidden" /> <input name="item_quantity_1" value="1" type="hidden" /> <input name="item_expiration_date_1" value="2010-10-28T21:00:00-9:00" type="hidden" /> </form>

36

The Checkout by Amazon Shopping Cart Guide

13 Appendix E: The Checkout by Amazon Shopping Cart Schema Definitions

Here is the listing of elements and their definitions for orders processed by Amazon Payments.

A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|Q|R|S|T|U|V|W|X|Y|Z A
aws_access_key_id Use Shopping Cart Integration using CSS Attributes Definition Merchants Access Key ID, used to build and verify the Signature on the server side, a page-level parameter, and defined in globalParamters div. Required Yes, if merchant_signature defined at item-level. <input name="aws_access_key_id" value="Error! Bookmark not defined." Example type="hidden">

C
cart_promotion_n Use Shopping Cart Integration using CSS Attributes Definition The promotion set for the entire cart, a page-level parameter, and defined in globalParameters div. Note that when cart_promotion_n is used, no item-level overrides are possible. No If discount_rate is used for cart_promotion_type, the cart_promotion value is used as a Rate discount. If fixed_amount_off is used for cart_promotion_type, the cart_promotion value is used as a discount amount from the total Price. The total discount amount cannot exceed the total cost of all items (if shipping and handling are not taxed) or the amount of the entire order (if shipping and handling are taxed). <input name="cart_promotion_1" value="5.49" type="hidden">

Required Value/Range

Example

cart_promotion_type_n Use Shopping Cart Integration using CSS Attributes Definition The type of promotion, a page-level parameter, and defined in globalParameters div. If discount_rate is used, the cart_promotion value is used as a Rate discount. If fixed_amount_off is used, the cart_promotion value is used as a discount amount from the total Price. Yes, if cart_promotion_n is used. discount_rate | fixed_amount_off <input name="cart_promotion_type_1" value="fixed_amount_off" type="hidden">

Required Value/Range Example

37

 2009 Amazon.com, Inc. or its Affiliates

client_request_id Use Shopping Cart Integration using CSS Attributes Definition User-defined identifier for requests, a page level parameter, and defined in globalParameters div. Required No <input name="client_request_id" value="123456"/> Example currency_code Use Shopping Cart Integration using CSS Attributes Definition The type of currency used for your Price, a page-level parameter, and defined in globalParameters div. Currently only USD is accepted. Yes USD <input name="currency_code" value="USD"/>

Required Value/Range Example

I
integrator_id Use Definition Required Value/Range Example Shopping Cart Integration using CSS Attributes The ID of the integrator helping integrate the merchant with Amazon Payments, a page-level parameter, and defined in globalParameters div. No

255 characters
<input name="integrator_id" value="VWXYZ98765VWXYZ" type="hidden">

integrator_name Use Shopping Cart Integration using CSS Attributes Definition The name of the integrator helping integrate the merchant with Amazon Payments, a pagelevel parameter, and defined in globalParameters div. Required No Value/Range 255 characters <input name="integrator_name" value="www.IntegratorWorld.com" Example type="hidden"> is_shipping_taxed Use Shopping Cart Integration using CSS Attributes Definition Specifies whether you charge tax for shipping and handling, a page-level parameter, and defined in globalParameters div. Required No. Default value is true. Value/Range Boolean <input name="is_shipping_taxed" value="false" type="hidden"> Example

38

The Checkout by Amazon Shopping Cart Guide

item_category Use Shopping Cart Integration using CSS Attributes Definition The selling group your Item belongs to, an item-level attribute, and defined under the html element with the class specified as item. Required No. Antiques | Apparel, Shoes & Accessories | Automotive | Beauty | Books | Value/Range Business | Cameras & Photography | Collectibles | Computer Hardware & Accessories | Electronics | Food, Drink & Nutrition | Gifts & Flowers | Healthcare | Hobbies, Toys & Games | Home & Garden | Jewelry & Watches | Media & Entertainment | Pets & Animals | Software | Sports & Recreation | Travel <span class="item_category" value="Books"></span> Example item_condition Use Shopping Cart Integration using CSS Attributes Definition The condition of the item, an item-level attribute, and defined under the html element with the class specified as item. Required No Any | Club | Collectible | New | Refurbished | Used Value/Range <input class="item_condition" value="New" type="hidden"> Example item_custom_attribute Use Shopping Cart Integration using CSS Attributes Definition Defines any merchant custom information in cart, an item-level attribute, and defined under the html element with the class specified as item. With each item_custom_attribute class tag, itemAttributeName must be defined. The value set for item_custom_attribute does not appear during checkout and does not appear in Seller Central. No. 255 characters <span class="item_custom_attribute" itemAttributeName="color">Blue</span>

Required Value/Range Example

item_description Use Shopping Cart Integration using CSS Attributes Definition The details about your Item, an item-level attribute, and defined under the html element with the class specified as item. Required No. Value/Range 255 characters <div class="item_description">The New England Wild Flower Society has Example completely updated the text and added 100 color photographs. The incredibly beautiful full-page drawings by Laura Foster are included from the original publication.</div>

39

 2009 Amazon.com, Inc. or its Affiliates

item_expiration_date Use Shopping Cart Integration using CSS Attributes Definition Defines the expiry of an item after the expiration date, the item will not exist in the cart; an item-level attribute, and defined under the html element with the class specified as item. Required No Value/Range UTC-formatted date <input class="item_expiration_date" value="2009-10-31:21:00-9:00" Example type="hidden" /> item_fulfillment_network Use Shopping Cart Integration using CSS Attributes Definition The method you use for fulfillment, yourself or Amazon, an item-level attribute, and defined under the html element with the class specified as item. Required No, if you have not signed up for Fulfillment by Amazon or you ship the order yourself. Yes, if you sign up for Fulfillment by Amazon and the Item is fulfilled by Amazon MERCHANT | AMAZON_NA <input type="radio" class="item_fulfillment_network" value="MERCHANT" selected>

Value/Range Example

item_image_url Use Shopping Cart Integration using CSS Attributes Definition The location for the image file used for the Item, an item-level attribute, and defined under the html element with the class specified as item. Required No; but if used, must include the protocol header http:// 255 characters Value/Range <img class="item_image_url" src="http://ecx.imagesExample amazon.com/images/I/41em%2BMZvdaL.jpg"> item_is_shipping_taxed Use Shopping Cart Integration using CSS Attributes Definition Specifies whether you charge tax on shipping and handling the Item, an item-level attribute, and defined under the html element with the class specified as item. Required No Boolean Value/Range <input class="item_is_shipping_taxed" value="true" type=hidden> Example item_price Use Definition Required Value/Range Example

Shopping Cart Integration using CSS Attributes The price of your Item, an item-level attribute, and defined under the html element with the class specified as item. Yes 0.01 99999.99 <span class="item_price">49.99</span>

40

The Checkout by Amazon Shopping Cart Guide

item_promotion Use Shopping Cart Integration using CSS Attributes Definition The promotion value for item, an item-level attribute, and defined under the html element with the class specified as item. Required No Value/Range If discount_rate is used for item_promotion_type, the item_promotion value is used as a rate discount. If fixed_amount_off is used for item_promotion_type, the item_promotion value is used as a discount amount from the total Price; Total discount amount cannot exceed the total cost of all items (if shipping and handling are not taxed) or the amount of the entire order (if shipping and handling are taxed). <input class="item_promotion" value="6" type="hidden" />

Example

item_promotion_type Use Shopping Cart Integration using CSS Attributes Definition The promotion value for item, an item-level attribute, and defined under the html element with the class specified as item. Required Yes, if cart_promotion is used. discount_rate | fixed_amount_off Value/Range <input class="item_promotion_type" value="fixed_amount_off" Example type="hidden" /> item_quantity Use Definition Required Value/Range Example item_sku Use Definition

Shopping Cart Integration using CSS Attributes The number sold for this item, an item-level attribute, and defined under the html element with the class specified as item. No; default is 1. 1-999 <input class="item_quantity" value="1" type="hidden" />

Required

Shopping Cart Integration using CSS Attributes The merchant-defined identification code (Stock-keeping Unit), a unique identifier for the item, an item-level attribute, and defined under the html element with the class specified as item. Yes, if you are using Fulfillment by Amazon for this Order. No, if you fulfill the item yourself. (See item_title.) If you set FulfillmentNetwork to AMAZON_NA, you must also include the item_sku_field in your order Shopping Cart Integration using CSS Attributes. 40 characters <input class="item_sku" value="XX-XXXX-XXXX" type="hidden" />

Value/Range Example item_tax_rate Use Definition Required Value/Range Example

Shopping Cart Integration using CSS Attributes The fee you want to charge for a specific tax rate, an item-level attribute, and defined under the html element with the class specified as item. No. 0.000001 0.15 <input class="item_tax_rate" value="0.052083" type="hidden" />

41

 2009 Amazon.com, Inc. or its Affiliates

item_tax_us_state_region Use Shopping Cart Integration using CSS Attributes Definition A U.S. state, an item-level attribute, and defined under the html element with the class specified as item. Required No. Value/Range 2-character string or us-all <input class="item_tax_us_state_region" value="CA" type="hidden" /> Example item_title Use Definition Required Value/Range Example item_url Use Definition Required Value/Range Example

Shopping Cart Integration using CSS Attributes The short description of your Item, an item-level attribute, and defined under the html element with the class specified as item. Yes. 100 characters <p class="item_title">Red Fish</p>

Shopping Cart Integration using CSS Attributes The location for the online description of the Item, an item-level attribute, and defined under the html element with the class specified as item. No; but if used, must include the protocol header http:// 255 characters <a class="item_url" href="http://mysite.com/item?636">Oliver Stops the Filibuster</a>

item_weight Use Definition Required Value/Range Example

Shopping Cart Integration using CSS Attributes The weight of the Item, an item-level attribute, and defined under the html element with the class specified as item. No; default unit is lb 0.01 99999.99 <input class="item_weight" value="4.25" type="hidden">

item_weight_unit Use Shopping Cart Integration using CSS Attributes Definition The type of weight, an item-level attribute, and defined under the html element with the class specified as item. Required No. lb Value/Range <input class="item_weight_unit" value="lb" type="hidden"> Example

42

The Checkout by Amazon Shopping Cart Guide

M
merchant_signature Use Shopping Cart Integration using CSS Attributes Definition The merchant-calculated signature of your Item. The merchant should sign both item-level and page-level attributes together. Required Yes, if signed carts are required. 512 characters Value/Range <input class="merchant_signature" Example value="OF8wRem0FzkbcvRsyno1PluzohVVGY5c3jHCz6Y8fDDf9EyeTj1xH6ozwPyTvmlU P2QfutuBwoBCgRtxmcleObyGk40G1nMdmsFcAWVaYqLmmIXSy1yOkQpq" type="hidden">

S
shipping_method_price_per_shipment_amount_n Use Shopping Cart Integration using CSS Attributes Definition The per-shipment amount charge, a page-level attribute, and defined in globalParameters div. No per-item charge is allowed. No. 0.01 99999.99 <input name="shipping_method_price_per_shipment_amount_1" value="8.5" type="hidden">

Required Value/Range Example

shipping_method_price_per_unit_rate_n Use Shopping Cart Integration using CSS Attributes Definition The unit rate charged for shipping the Item using this shipping method, a page-level attribute, and defined in globalParameters div. Required No. 0.01 99999.99 Value/Range <input name="shipping_method_price_per_unit_rate_1" value="5.00" Example type="hidden"> shipping_method_price_type_n Use Shopping Cart Integration using CSS Attributes Definition The type of calculation used for the Item shipping method, a page-level attribute, and defined in globalParameters div. Required No. weight_based | item_quantity_based Value/Range <input name="shipping_method_price_type_1" value="weight_based" Example type="hidden">

43

 2009 Amazon.com, Inc. or its Affiliates

shipping_method_region_n Use Shopping Cart Integration using CSS Attributes Definition The shipping region for the Item when using this shipping method, a page-level attribute, and defined in globalParameters div. Each shipping region n in the Item description has its own method region n in the shipping method definition. No. us_all | world_all | us_continental_48_states | us_full_50_states <input name="shipping_method_region_1" value="us_full_50_states" type="hidden">

Required Value/Range Example

shipping_method_service_level_n Use Shopping Cart Integration using CSS Attributes Definition The name of the level of service you are defining, a page-level attribute, and defined in globalParameters div. This text appears to the buyer in the checkout pipeline. Note that one_day and two_day service is available only for orders fulfilled by Fulfillment by Amazon. This is different from XML-based carts. No. standard | expedited | one_day| two_day <input name="shipping_method_service_level_1" value="standard" type="hidden">

Required Value/Range Example

T
tax_rate Use Definition Shopping Cart Integration using CSS Attributes The rate to be charged for the tax, a page-level attribute, and defined in globalParameters div. Can apply just for Items, or for Items as well as shipping and handling. (See is_shipping_taxed.) No. 0.000001 0.15 <input name="tax_rate" value="0.07375" type="hidden">

Required Value/Range Example

tax_us_state_region Use Shopping Cart Integration using CSS Attributes Definition The tax rule to apply according to the state, a page-level attribute, and defined in globalParameters div. Required No. Value/Range 2-character string <input name="tax_us_state_region" value="WA" type="hidden"> Example

44