Upload
caioeduardocosta
View
49
Download
3
Tags:
Embed Size (px)
Citation preview
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
The Checkout by Amazon Shopping Cart Guide
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
The Checkout by Amazon Shopping Cart Guide
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:
© 2009-11 Amazon.com, Inc. or its Affiliates
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.
The Checkout by Amazon Shopping Cart Guide
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
© 2009-11 Amazon.com, Inc. or its Affiliates
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.
The Checkout by Amazon Shopping Cart Guide
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> <!-- 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
6
<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
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.
© 2009-11 Amazon.com, Inc. or its Affiliates
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.
The Checkout by Amazon Shopping Cart Guide
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> <!-- 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
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> $
The Checkout by Amazon Shopping Cart Guide
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.
© 2009-11 Amazon.com, Inc. or its Affiliates
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.
The Checkout by Amazon Shopping Cart Guide
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:
© 2009-11 Amazon.com, Inc. or its Affiliates
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.
The Checkout by Amazon Shopping Cart Guide
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:
© 2009-11 Amazon.com, Inc. or its Affiliates
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):
The Checkout by Amazon Shopping Cart Guide
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> <!-- 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 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
<!-- 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> 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 ...> <!-- code to display items--> </form> ...
When you are done, your webpage will look like this:
The Checkout by Amazon Shopping Cart Guide
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.
© 2009 Amazon.com, Inc. or its Affiliates
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>
The Checkout by Amazon Shopping Cart Guide
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'} ]
© 2009 Amazon.com, Inc. or its Affiliates
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:
<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.
The Checkout by Amazon Shopping Cart Guide
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:
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:
© 2009 Amazon.com, Inc. or its Affiliates
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?
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> 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.
The Checkout by Amazon Shopping Cart Guide
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.
© 2009 Amazon.com, Inc. or its Affiliates
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.
<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.
The Checkout by Amazon Shopping Cart Guide
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.
<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.
© 2009 Amazon.com, Inc. or its Affiliates
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
The Checkout by Amazon Shopping Cart Guide
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"> <!-- 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).
© 2009 Amazon.com, Inc. or its Affiliates
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
The Checkout by Amazon Shopping Cart Guide
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> <!-- This is the navigation and branding area of the webpage --> <table>
© 2009 Amazon.com, Inc. or its Affiliates
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 ...> <!-- 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-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>
The Checkout by Amazon Shopping Cart Guide
33
</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.
That’s it! For more information on order management and next steps to follow, see the Checkout by
Amazon Getting Started Guide (PDF).
© 2009 Amazon.com, Inc. or its Affiliates
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.
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.
The Checkout by Amazon Shopping Cart Guide
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>
© 2009 Amazon.com, Inc. or its Affiliates
36
</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>
The Checkout by Amazon Shopping Cart Guide
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
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.
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
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.
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">
© 2009 Amazon.com, Inc. or its Affiliates
38
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
Example <input name="client_request_id" value="123456"/>
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.
Required Yes
Value/Range USD
Example <input name="currency_code" value="USD"/>
I
integrator_id
Use Shopping Cart – Integration using CSS Attributes
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
Use Shopping Cart – Integration using CSS Attributes
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
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
Example <input name="is_shipping_taxed" value="false" type="hidden">
The Checkout by Amazon Shopping Cart Guide
39
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.
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
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
Value/Range Any | Club | Collectible | New | Refurbished | Used
Example <input class="item_condition" value="New" type="hidden">
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.
Required No.
Value/Range 255 characters
Example <span class="item_custom_attribute" itemAttributeName="color">Blue</span>
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
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>
© 2009 Amazon.com, Inc. or its Affiliates
40
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
Example <input class="item_expiration_date" value="2009-10-31:21:00-9:00" 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
Value/Range MERCHANT | AMAZON_NA
Example <input type="radio" class="item_fulfillment_network" value="MERCHANT" selected>
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://
Value/Range 255 characters
Example <img class="item_image_url" src="http://ecx.images-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
Value/Range Boolean
Example <input class="item_is_shipping_taxed" value="true" type=hidden>
item_price
Use Shopping Cart – Integration using CSS Attributes
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>
The Checkout by Amazon Shopping Cart Guide
41
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).
Example <input class="item_promotion" value="6" type="hidden" />
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.
Value/Range discount_rate | fixed_amount_off
Example <input class="item_promotion_type" value="fixed_amount_off" type="hidden" />
item_quantity
Use Shopping Cart – Integration using CSS Attributes
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
Use Shopping Cart – Integration using CSS Attributes
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.
Value/Range 40 characters
Example <input class="item_sku" value="XX-XXXX-XXXX" type="hidden" />
item_tax_rate
Use Shopping Cart – Integration using CSS Attributes
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" />
© 2009 Amazon.com, Inc. or its Affiliates
42
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
Example <input class="item_tax_us_state_region" value="CA" type="hidden" />
item_title
Use Shopping Cart – Integration using CSS Attributes
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.
Value/Range 100 characters
Example <p class="item_title">Red Fish</p>
item_url
Use Shopping Cart – Integration using CSS Attributes
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://
Value/Range 255 characters
Example <a class="item_url" href="http://mysite.com/item?636">Oliver Stops the Filibuster</a>
item_weight
Use Shopping Cart – Integration using CSS Attributes
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
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.
Value/Range lb
Example <input class="item_weight_unit" value="lb" type="hidden">
The Checkout by Amazon Shopping Cart Guide
43
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.
Value/Range 512 characters
Example <input class="merchant_signature" value="OF8wRem0FzkbcvRsyno1PluzohVVGY5c3jHCz6Y8fDDf9EyeTj1xH6ozwPyTvmlUP2QfutuBwoBCgRtxmcleObyGk40G1nMdmsFcAWVaYqLmmIXSy1yOkQpq" 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.
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
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.
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
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.
Value/Range weight_based | item_quantity_based
Example <input name="shipping_method_price_type_1" value="weight_based" type="hidden">
© 2009 Amazon.com, Inc. or its Affiliates
44
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.
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
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.
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
Use Shopping Cart – Integration using CSS Attributes
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
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
Example <input name="tax_us_state_region" value="WA" type="hidden">