Amazon Webstore Add to Cart API Reference

Amazon Webstore Add to Cart API Reference

Amazon Webstore Add to Cart API Reference

1

Amazon Webstore Add to Cart API Reference

Contents Amazon Webstore Add to Cart API Reference......................................................................................... 3 What you should know about the Add to Cart API .................................................................................. 4 URI............................................................................................................................................................. 4 FIELDS ...................................................................................................................................................... 4 Headers ..................................................................................................................................................... 5 Cookies ...................................................................................................................................................... 5 Request ........................................................................................................................................................ 5 Response ..................................................................................................................................................... 7 Example Code ............................................................................................................................................. 8 Error Codes ................................................................................................................................................. 9 License ....................................................................................................................................................... 10

Amazon Webstore Add to Cart API Reference

2

Amazon Webstore Add to Cart API Reference

Amazon Webstore Add to Cart API Reference Amazon Webstore Add to Cart API Copyright (c) 2014 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Amazon Software License (the "License"). You may not use this API except in compliance with the License. A copy of the License is located at http://aws.amazon.com/asl/ or in the "License" set forth in detail below in this documentation. This API is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions and limitations under the License. Last updated: 2014-04-04

Amazon Webstore Add to Cart API Reference

3

Amazon Webstore Add to Cart API Reference

What you should know about the Add to Cart API The Amazon Webstore Website Customization APIs include an Add to Cart API. The API is designed to provide sellers the ability to build within-the-website applications to place products in the customer’s cart. It is designed to be guest facing and real-time. Requests are made for an individual item to be added to the customer’s cart and the API returns the cart with all cart items. With access to the API, you can create enhanced JavaScript and Flash applications to build exciting new features for your site. You may also build more sophisticated applications that run outside of your site. Notes: • •

The Add to Cart API is not intended for bulk/reporting usage. Associate products are not supported by the Amazon Webstore Website Customization APIs.

URI The following is an example of how to add an item to the cart. Cart requires a POST to add a cart item:

POST http://{yourWebstoreDomain}/api/cart/{cartId}/items

• •

yourWebstoreDomain: The URL to your site. You can find the URL on the Seller Central homepage or on the Domain Name page. cartId: An identifier for the cart resource. The site uniquely identifies cart through the customer’s session ID, which is available in the session-id cookie. See the Cookie section below for more information.

FIELDS cartItems: AXXXXXXXXXXXXX XXXXXSKUXXXX # XXOFFERLISTINGIDXX

Amazon Webstore Add to Cart API Reference

4

Amazon Webstore Add to Cart API Reference

CURL Example

/usr/bin/curl -v -X POST \ --data-binary "AXXXXXXXXXXXXX091TJ148 58061" \ -H "Accept: text/xml" \ -H "Cookie: session-id=181-4199423-4641214;" \ http://yourWebstoreDomain.com/api/cart/181-4199423-4641214/items

Headers To specify the desired format of the response, use the Accept header.

Accept: Accept: Accept: Accept:

text/json application/json text/xml application/xml

//JSON - Human-readable (default) //JSON - optimized for programs //XML - human-readable //XML - optimized for programs

By default, the API returns human-readable JSON.

Cookies The Webstore Add to Cart API requires the session-id cookie to be present. This session-id is also used to identify the cart. The session-id cookie can be read, and passed in the URL as the cart identifier.

session-id:



Example:

NAME: VALUE: DOMAIN: PATH: EXPIRES:

session-id 188-2762727-5500859 myDomainName.com / 9/28/2013 12:00:00 AM

Request The API requires a full cartItems document to be passed. The cartItems and cartItem have the following schema:

Amazon Webstore Add to Cart API Reference

5

Amazon Webstore Add to Cart API Reference

cartItems Schema

cartItem Schema



Amazon Webstore Add to Cart API Reference

6

Amazon Webstore Add to Cart API Reference

cartItem product The cartItem product requires identifiers to be present. Identifiers can be in the form of merchant SKU or ASIN structures. cartItem quantity The cartItem quantity is a simple integer value indicating the number of this product to add to cart. This will increment any existing quantities already in the cart. cartItem offerListingId The cartItem offerListingId is an optional unique identifier that is a unique merchant listing for a sellable product. For example, this identifier can be used to distinguish old versus new product offer listings. The value is available from Product. See the Webstore Product API documentation for more details. Note: If you have products with multiple offers, we recommend that you add them to cart by SKU or offerListingId. If you add a product by ASIN, and the product has multiple offers, the API will return an error message. Example AXXXXXXXXXXXXX BH00048 1

Response The API returns the cartItems resource. See the Request section above for more details. Example

B0032TYMJG 23

Amazon Webstore Add to Cart API Reference

7

Amazon Webstore Add to Cart API Reference

tQZgM2yISKgXmA%2FFhK7454vgy0%2BPmjksgMeC5ykNEVrdpjrChjAPEuh HtqFuPJ7b7b7tbgnrCYhhC2byFXeUycV8fnEbvhWL8RsfqfbNV79%2BCQimAeo3d1j9afv8iiZAEA Ek2PMfdHo%3D B0032TYN8Q 1 ZqnREcXD80f9kbHlimxyH4l92P%2BRykFUqKnidkXjZCN9ugT7rLhXm%2Bd GgLvZG4q5cDnAx%2Ft3p2oCQnVCduGxaPynC7ms5vxY8P4V%2BVlEu5ikR9Ls0ZFiuO9EfbFORbtO 8%2FIJrIMLvpA%3D

Example Code JavaScript

//JQuery { var sessionid = ReadCookie('session-id'); jQuery.ajax({ type: 'POST', url: '/api/cart/' + sessionid + '/items', data: ''+asin+'1', dataType: 'xml', }); } function ReadCookie(cookieName) { var theCookie=""+document.cookie; var ind=theCookie.indexOf(cookieName); if (ind==-1 || cookieName=="") return ""; var ind1=theCookie.indexOf(';',ind); if (ind1==-1) ind1=theCookie.length; return unescape(theCookie.substring(ind+cookieName.length+1,ind1)); }

Amazon Webstore Add to Cart API Reference

8

Amazon Webstore Add to Cart API Reference

Example - Update Mini Cart When used within your Amazon Webstore, it is important to update the mini cart that displays the number of items in your cart. Below is example code that describes how to complete this process. Note: The sample code is provided as-is and is intended for illustration purposes only.

if (statusText == 'success') { if (!response.responseXML) { var res = new DOMParser().parseFromString(response.responseText, "text/xml"); } else { var res = response.responseXML; } //console.log(res); var quantities = res.getElementsByTagName('c:quantity'); var cartItemCount = 0; for(var i = 0; i < quantities.length; i++) { var quantityValue = parseInt(quantities.item(i).firstChild.nodeValue); cartItemCount = cartItemCount + parseInt(quantityValue); } //console.log(miniCart.containerSelector)/ //"#topSlots #miniCart" //console.log(miniCart.itemCountSelector); //".cartInformation .itemCount" var container = jQuery(miniCart.itemCountSelector); //var itemCount = jQuery('span.itemCount', container); var itemCountHTML = '' + cartItemCount + ''; container.replaceWith( itemCountHTML ); //console.log(container); }

Error Codes Error Code 400

Exception Type InvalidSchemaException

400

InvalidInputException

403

ForbiddenException

404

InvalidIDException

406

NotAcceptableException

500

InternalFailureException

Amazon Webstore Add to Cart API Reference

Description Cart request input does not conform to the acceptable schema. Please provide a valid input. An input value is invalid. Please provide a valid input. You do not have access to the requested operation. The SKU or ASIN is invalid. Please enter a valid product ID. The contents in the Accept header cannot be verified. Please fix the header and try again. An internal service error has occurred. Please try your request again later.

9

Amazon Webstore Add to Cart API Reference

License Amazon Software License This Amazon Software License (“License”) governs your use, reproduction, and distribution of the accompanying software as specified below. 1. Definitions “Licensor” means any person or entity that distributes its Work. “Software” means the original work of authorship made available under this License. “Work” means the Software and any additions to or derivative works of the Software that are made available under this License. The terms “reproduce,” “reproduction,” “derivative works,” and “distribution” have the meaning as provided under U.S. copyright law; provided, however, that for the purposes of this License, derivative works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work. Works, including the Software, are “made available” under this License by including in or with the Work either (a) a copyright notice referencing the applicability of this License to the Work, or (b) a copy of this License. 2. License Grants 2.1 Copyright Grant. Subject to the terms and conditions of this License, each Licensor grants to you a perpetual, worldwide, non-exclusive, royalty-free, copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense and distribute its Work and any resulting derivative works in any form. 2.2 Patent Grant. Subject to the terms and conditions of this License, each Licensor grants to you a perpetual, worldwide, non-exclusive, royalty-free patent license to make, have made, use, sell, offer for sale, import, and otherwise transfer its Work, in whole or in part. The foregoing license applies only to the patent claims licensable by Licensor that would be infringed by Licensor’s Work (or portion thereof) individually and excluding any combinations with any other materials or technology. 3. Limitations 3.1 Redistribution. You may reproduce or distribute the Work only if (a) you do so under this License, (b) you include a complete copy of this License with your distribution, and (c) you retain without modification any copyright, patent, trademark, or attribution notices that are present in the Work. 3.2 Derivative Works. You may specify that additional or different terms apply to the use, reproduction, and distribution of your derivative works of the Work (“Your Terms”) only if (a) Your Terms provide that the use limitation in Section 3.3 applies to your derivative works, and (b) you identify the specific derivative works that are subject to Your Terms. Notwithstanding Your Terms, this License (including the redistribution requirements in Section 3.1) will continue to apply to the Work itself. 3.3 Use Limitation. The Work and any derivative works thereof only may be used or intended for use with the web services, computing platforms or applications provided by Amazon.com, Inc. or its affiliates.

Amazon Webstore Add to Cart API Reference

10

Amazon Webstore Add to Cart API Reference

3.4 Patent Claims. If you bring or threaten to bring a patent claim against any Licensor (including any claim, crossclaim or counterclaim in a lawsuit) to enforce any patents that you allege are infringed by any Work, then your rights under this License from such Licensor (including the grants in Sections 2.1 and 2.2) will terminate immediately. 3.5 Trademarks. This License does not grant any rights to use any Licensor’s or its affiliates’ names, logos, or trademarks, except as necessary to reproduce the notices described in this License. 3.6 Termination. If you violate any term of this License, then your rights under this License (including the grants in Sections 2.1 and 2.2) will terminate immediately. 4. Disclaimer of Warranty. THE WORK IS PROVIDED “AS IS” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OR CONDITIONS OF M ERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT. YOU BEAR THE RISK OF UNDERTAKING ANY ACTIVITIES UNDER THIS LICENSE. SOME STATES’ CONSUMER LAWS DO NOT ALLOW EXCLUSION OF AN IMPLIED WARRANTY, SO THIS DISCLAIMER MAY NOT APPLY TO YOU. 5. Limitation of Liability. EXCEPT AS PROHIBITED BY APPLICABLE LAW, IN NO EVENT AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE SHALL ANY LICENSOR BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATED TO THIS LICENSE, THE USE OR INABILITY TO USE THE WORK (INCLUDING BUT NOT LIMITED TO LOSS OF GOODWILL, BUSINESS INTERRUPTION, LOST PROFITS OR DATA, COMPUTER FAILURE OR MALFUNCTION, OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES), EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Effective Date – April 18, 2008 © 2008 Amazon.com, Inc. or its affiliates. All rights reserved.

Amazon Webstore Add to Cart API Reference

11