Shopping Cart Guide

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

ii

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 What’s New in This Document .................................................................................................... 3

2 Enable the Checkout by Amazon Shopping Cart Functionality ....................................................... 4 3 Add a Navigation Link to Display the Shopping Cart ........................................................................ 5 4 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

5 Modify Your Shopping Cart Security Settings ................................................................................. 13 6 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 7 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

8 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 cart’s 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


iii

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


1

1 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:


2

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 you’ve 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 functionality–you 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 cart—you enable the appearance of the pop-

up 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 buttons—you 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 Settings—you 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

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

Resource Audience, Purpose, and Goals

Getting Started Guide (PDF)

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.

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

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.

https://payments.amazon.com/sdui/sdui/business/cba/shoppingcart

https://payments.amazon.com/sdui/sdui/business/cba/shoppingcart

https://sellercentral.amazon.com/gp/on-board/workflow/Registration/login.html/902-0586098-4611057?passthrough%2Fsource=AmazonCheckout&passthrough%2Fld=AP&passthrough%2Faccount=cba&passthrough%2FsuperSource=OAR&passthrough%2FmarketplaceID=AZ4B0ZS3LGLX

http://amazonpayments.s3.amazonaws.com/documents/Getting_Started_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/ImplementationGuideBTN.pdf



http://amazonpayments.s3.amazonaws.com/documents/ImplementationGuideHTML.pdf




3

Resource Audience, Purpose, and Goals

Standard Checkout - XML Implementation Guide

Using Seller Central (PDF) For merchants who want an overview of Seller Central.

Best Practices Guide (PDF)

Contains the best tips for merchants who want to set up their websites to use Amazon Payments, with advice for planning, setting up, and day-to-day operations.

Launch Checklist (PDF) Launch Checklist (XLS)

For merchants and developers planning to set up and use Checkout by Amazon on their site.

Callback API Guide (PDF) 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 the Callback API (PDF)

For developers who want a quick, 1-page summary of how to enable callbacks.

Instant Order Processing Notifications API Guide (PDF)

For developers who want to automate order notifications with Amazon Payments.

Using Custom Data Fields (PDF)

For merchants and developers who want to include custom data fields in their carts.

The Checkout by Amazon Shopping Cart Guide (PDF)

For merchants and developers who want to use the Checkout by Amazon Shopping Cart on their site.

Using Checkout by Amazon as a Payment Option (PDF)

For developers interested in Checkout by Amazon as an alternate payment method on their site.

Open-Source Shopping Cart Solutions (PDF)

For developers interested in open-source carts that support Checkout by Amazon (currently osCommerce 1.x and Zen Cart).

osCommerce Installation and Configuration Guide (PDF)

For developers interested in the osCommerce open source cart, v. 2.0 and greater.

1.3 What’s New in This Document Ver Date Changes

1.4 2011-08-12 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

1.3 2011-07-14 Added a link to the Shopping Cart page on the Amazon Payments site.

1.0 2009-05-27 Initial Release

http://amazonpayments.s3.amazonaws.com/documents/ImplementationGuideXML.pdf



http://amazonpayments.s3.amazonaws.com/documents/Using_Seller_Central.pdf

http://amazonpayments.s3.amazonaws.com/documents/Best_Practices_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/LaunchChecklist.pdf

http://amazonpayments.s3.amazonaws.com/documents/LaunchChecklist.xls

http://amazonpayments.s3.amazonaws.com/documents/Callback_API_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/Callback_API_Guide.2008-11-30.pdf

http://amazonpayments.s3.amazonaws.com/documents/Callback_API_DCS.pdf

http://amazonpayments.s3.amazonaws.com/documents/Callback_API_DCS.pdf

http://amazonpayments.s3.amazonaws.com/documents/Instant_Order_Processing_Notification_API_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/Instant_Order_Processing_Notification_API_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/Using_Custom_Data_Fields.pdf

http://amazonpayments.s3.amazonaws.com/documents/Shopping_Cart_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/Shopping_Cart_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/Using_Checkout_by_Amazon_As_a_Payment_Option.pdf



http://amazonpayments.s3.amazonaws.com/documents/Open-source_Shopping_Cart_Solutions.pdf

http://amazonpayments.s3.amazonaws.com/documents/Open-source_Shopping_Cart_Solutions.pdf

http://amazonpayments.s3.amazonaws.com/documents/osCommerce_Install_and_Configure.pdf

http://amazonpayments.s3.amazonaws.com/documents/osCommerce_Install_and_Configure.pdf


4

2 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-images-amazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-images-amazon.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-images-amazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-images-amazon.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.


5

3 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 we’ve snipped out to make this example clearer):

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <html> <head> ... </head> <body>  <table> <tr> <td colspan="2"><img src="Logo.png" alt="" /></td> </tr> <tr> <td></td> <td width="450">


6

<b>View Cart</b> </td> </tr> <tr> <td colspan="2"><td> </tr> </table>  ...

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>  <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>  ...


7

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.

https://sellercentral.amazon.com/


8

4 Use CSS Attributes to Integrate Add to Cart Buttons After you’ve 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;

it’s 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.


http://amazonservices.s3.amazonaws.com/Payments/documents/Getting_Started_Guide.pdf


9

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 Settings—the 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-images-amazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script> </head> <body>  <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>  <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>  <table> ...



10

</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 CSS-

based Shopping Cart for a list of the tags you can use.

Suppose, for example, you want to display the following products:

Here’s 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> $ <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> $


11

<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 clickable—and 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.


12

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.


13

5 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, you’ll 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:



14

3. Click the Update button, and note that the Shopping Cart Security setting now shows

“Disabled”:

That’s it! By adding these CSS attributes to your webpage, you’re 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.



15

6 Optional Features of the Shopping Cart You can modify your Checkout by Amazon Shopping Cart further with these optional features:

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

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:


https://sellercentral.amazon.com/gp/cba/seller/shoppingcart/settings/user-settings-view.html

https://sellercentral.amazon.com/gp/cba/seller/shoppingcart/settings/user-settings-view.html


16

You can set the following values, as shown in this illustration:

1. Widget body color

2. Scroll window color

3. Widget body text color

4. 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 we’ve snipped out to make this example clearer):


17

<!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-images-amazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script> </head> <body>  <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 ...>  </form> ...

To have the total item count appear on your webpage, you add the following entries to your code

(note that the 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-images-amazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-images-amazon.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>

© 2009 Amazon.com, Inc. or its Affiliates

18

 <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>   Item(s) <span class="amazonPaymentsCart_TotalItems"></span>   Subtotal: $ <span class="amazonPaymentsCart_SubTotal"></span> </div> </div> </td> </tr> <tr> <td colspan="2"><td> </tr> </table> <form method=POST ...>  </form> ...

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


19

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 attributes—include 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 attributes—include more information in the shopping cart window

6.3.1 Data attributes

To add the Data attribute (that is, an attribute that’s 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.


20

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>


21

7 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'} ]


22

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:


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:


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


23

8 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:



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:


24

<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 you’re new to Checkout by Amazon, CSS attributes might be the easiest

way to build pages with many products for sale, because you don’t 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?



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>   Item(s) <span class="amazonPaymentsCart_TotalItems"></span>   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>   Item(s) <span class="amazonPaymentsCart_TotalItems"></span>   Subtotal: $ <span class="amazonPaymentsCart_SubTotal"></span> </div> </div>

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


25

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.


26

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 cart’s 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.


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.


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


27

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.


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.

http://amazonservices.s3.amazonaws.com/Payments/documents/Integration_Guide.pdf

http://amazonservices.s3.amazonaws.com/Payments/documents/Callback_API_Guide.pdf

http://amazonservices.s3.amazonaws.com/Payments/documents/Instant_Order_Processing_Notifications_API_Guide.pdf

http://amazonservices.s3.amazonaws.com/Payments/documents/Instant_Order_Processing_Notifications_API_Guide.pdf


28

9 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 Notes

Item

item_category item_condition item_custom_attribute 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_description item_fulfillment_network item_image_url item_is_shipping_taxed item_price Required item_expiration_date item_promotion item_promotion_type item_quantity item_sku Required when using Fulfillment by

Amazon. item_tax_rate item_tax_us_state_region item_title Required item_url item_weight item_weight_unit merchant_signature if signed carts are required, item-

level 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


29

Level Attribute Name Notes shipping_method_region cart_promotion cart_promotion_type tax_rate tax_us_state_region is_shipping_taxed

Example of an item-level element:

<table class="item">  <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).

http://amazonservices.s3.amazonaws.com/Payments/documents/Developers_Guide.pdf


30

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 Description <img> The src attribute of the image. Ignored if src is empty. <input type="radio"> The value attribute if the radio button is checked. Ignored if not

checked. <input type="checkbox"> The value attribute if the checkbox is checked. Ignored if not

checked. <input type="file">

Ignored.

<input type="image"> The src value. Ignored if type is empty.

<input> with any other type (for example, hidden, text, password, and so on)

The value attribute of this element. Ignored if the value is empty.

<a href> Value of href. Its value should be a well-formed URL. <iframe> Ignored. <select> <select-one>

Value of selected option <select class="item_custom_attribute" itemAttributeName="color"> <option value="Red">Red</option> <option value="Blue”>Blue</option> </select>

All Other Elements 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


31

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 Benefit Skill

Use CSS Attributes to Build a Checkout Solution

Quick, easy way to set up your pages.

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.

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

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

You use your XML or HTML programming skills to create buttons.

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 we’ve 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>  <table>




32

<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 ...>  </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-images-amazon.com/images/G/01/cba/js/common/cba_shared.js" type="text/javascript"></script> <script src="https://images-na.ssl-images-amazon.com/images/G/01/cba/js/shoppingcart/merchant_cart.js" type="text/javascript"></script>


33

</head> <body>  <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 ...>  </form> ...

The results will look something like this:

Note that the “Checkout by Amazon” buttons are automatically changed to “Add to Cart” buttons.

That’s it! For more information on order management and next steps to follow, see the Checkout by

Amazon Getting Started Guide (PDF).



34

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.


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.



http://amazonservices.s3.amazonaws.com/Payments/documents/Developers_Guide.pdf

http://amazonservices.s3.amazonaws.com/Payments/documents/Using_Custom_Data_Fields.pdf





35

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>


36

</ItemCustomData> </Item> ...


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>


37

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 Merchant’s 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.

Example <input name="aws_access_key_id" value="Error! Bookmark not defined." type="hidden">

C

cart_promotion_n


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.

Required No

Value/Range 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).

Example <input name="cart_promotion_1" value="5.49" type="hidden">

cart_promotion_type_n


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.

Required Yes, if cart_promotion_n is used.

Value/Range discount_rate | fixed_amount_off

Example <input name="cart_promotion_type_1" value="fixed_amount_off" type="hidden">


38

client_request_id


Definition User-defined identifier for requests, a page level parameter, and defined in globalParameters div.

Required No

Example <input name="client_request_id" value="123456"/>

currency_code


Definition The type of currency used for your Price, a page-level parameter, and defined in globalParameters div. Currently only USD is accepted.

Required Yes

Value/Range USD

Example <input name="currency_code" value="USD"/>

I

integrator_id


Definition The ID of the integrator helping integrate the merchant with Amazon Payments, a page-level parameter, and defined in globalParameters div.

Required No

Value/Range 255 characters Example <input name="integrator_id" value="VWXYZ98765VWXYZ" type="hidden">

integrator_name


Definition The name of the integrator helping integrate the merchant with Amazon Payments, a page-level parameter, and defined in globalParameters div.

Required No

Value/Range 255 characters

Example <input name="integrator_name" value="www.IntegratorWorld.com" type="hidden">

is_shipping_taxed


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

Example <input name="is_shipping_taxed" value="false" type="hidden">


39

item_category


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.

Value/Range Antiques | Apparel, Shoes & Accessories | Automotive | Beauty | Books | 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

Example <span class="item_category" value="Books"></span>

item_condition


Definition The condition of the item, an item-level attribute, and defined under the html element with the class specified as item.

Required No

Value/Range Any | Club | Collectible | New | Refurbished | Used

Example <input class="item_condition" value="New" type="hidden">

item_custom_attribute


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.

Required No.


Example <span class="item_custom_attribute" itemAttributeName="color">Blue</span>

item_description


Definition The details about your Item, an item-level attribute, and defined under the html element

with the class specified as item.

Required No.


Example <div class="item_description">The New England Wild Flower Society has 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>


40

item_expiration_date


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

Example <input class="item_expiration_date" value="2009-10-31:21:00-9:00" type="hidden" />

item_fulfillment_network


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

Value/Range MERCHANT | AMAZON_NA

Example <input type="radio" class="item_fulfillment_network" value="MERCHANT" selected>

item_image_url


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://


Example <img class="item_image_url" src="http://ecx.images-amazon.com/images/I/41em%2BMZvdaL.jpg">

item_is_shipping_taxed


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

Value/Range Boolean

Example <input class="item_is_shipping_taxed" value="true" type=hidden>

item_price


Definition The price of your Item, an item-level attribute, and defined under the html element with the class specified as item.

Required Yes

Value/Range 0.01 – 99999.99

Example <span class="item_price">49.99</span>


41

item_promotion


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).

Example <input class="item_promotion" value="6" type="hidden" />

item_promotion_type


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.

Value/Range discount_rate | fixed_amount_off

Example <input class="item_promotion_type" value="fixed_amount_off" type="hidden" />

item_quantity


Definition The number sold for this item, an item-level attribute, and defined under the html element with the class specified as item.

Required No; default is 1.

Value/Range 1-999

Example <input class="item_quantity" value="1" type="hidden" />

item_sku


Definition 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.

Required 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.


Example <input class="item_sku" value="XX-XXXX-XXXX" type="hidden" />

item_tax_rate


Definition 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.

Required No.

Value/Range 0.000001 – 0.15

Example <input class="item_tax_rate" value="0.052083" type="hidden" />


42

item_tax_us_state_region


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

Example <input class="item_tax_us_state_region" value="CA" type="hidden" />

item_title


Definition The short description of your Item, an item-level attribute, and defined under the html element with the class specified as item.

Required Yes.


Example <p class="item_title">Red Fish</p>

item_url


Definition 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.

Required No; but if used, must include the protocol header http://


Example <a class="item_url" href="http://mysite.com/item?636">Oliver Stops the Filibuster</a>

item_weight


Definition The weight of the Item, an item-level attribute, and defined under the html element with the class specified as item.

Required No; default unit is lb

Value/Range 0.01 – 99999.99

Example <input class="item_weight" value="4.25" type="hidden">

item_weight_unit


Definition The type of weight, an item-level attribute, and defined under the html element with the class specified as item.

Required No.

Value/Range lb

Example <input class="item_weight_unit" value="lb" type="hidden">


43

M

merchant_signature


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.


Example <input class="merchant_signature" value="OF8wRem0FzkbcvRsyno1PluzohVVGY5c3jHCz6Y8fDDf9EyeTj1xH6ozwPyTvmlUP2QfutuBwoBCgRtxmcleObyGk40G1nMdmsFcAWVaYqLmmIXSy1yOkQpq" type="hidden">

S

shipping_method_price_per_shipment_amount_n


Definition The per-shipment amount charge, a page-level attribute, and defined in globalParameters div. No per-item charge is allowed.

Required No.

Value/Range 0.01 – 99999.99

Example <input name="shipping_method_price_per_shipment_amount_1" value="8.5" type="hidden">

shipping_method_price_per_unit_rate_n


Definition The unit rate charged for shipping the Item using this shipping method, a page-level attribute, and defined in globalParameters div.

Required No.

Value/Range 0.01 – 99999.99

Example <input name="shipping_method_price_per_unit_rate_1" value="5.00" type="hidden">

shipping_method_price_type_n


Definition The type of calculation used for the Item shipping method, a page-level attribute, and defined in globalParameters div.

Required No.

Value/Range weight_based | item_quantity_based

Example <input name="shipping_method_price_type_1" value="weight_based" type="hidden">


44

shipping_method_region_n


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.

Required No.

Value/Range us_all | world_all | us_continental_48_states | us_full_50_states

Example <input name="shipping_method_region_1" value="us_full_50_states" type="hidden">

shipping_method_service_level_n


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.

Required No.

Value/Range standard | expedited | one_day| two_day

Example <input name="shipping_method_service_level_1" value="standard" type="hidden">

T

tax_rate


Definition 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.)

Required No.

Value/Range 0.000001 – 0.15

Example <input name="tax_rate" value="0.07375" type="hidden">

tax_us_state_region


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

Example <input name="tax_us_state_region" value="WA" type="hidden">

Documents

Shopping Cart Guide