Menu
Product Advertising API
Developer Guide (API Version 2013-08-01)

CartModify

Description

The CartModify operation enables you to change the quantity of items that are already in a remote shopping cart and move items from the active area of a cart to the SaveForLater area or the reverse.

To modify the number of items in a cart, you must specify the cart using the CartId and HMAC values that are returned in the CartCreate operation. A value similar to HMAC, URLEncodedHMAC, is also returned. This value is the URL encoded version of the HMAC. This encoding is necessary because some characters, such as + and /, cannot be included in a URL. Rather than encoding the HMAC yourself, use the URLEncodedHMAC value for the HMAC parameter.

You can use CartModify to modify the number of items in a remote shopping cart by setting the value of the Quantity parameter appropriately. You can eliminate an item from a cart by setting the value of the Quantity parameter to zero. Or, you can double the number of a particular item in the cart by doubling its Quantity . You cannot, however, use CartModify to add new items to a cart.

All CartModify requests must also include the value for AssociateTag that was used in the associated CartCreate request; otherwise, the request will fail.

Availability

All locales.

Request Parameters

Name Description Required
Action

The Action parameter is a child element of the Item parameter in both SOAP requests. Use the Action parameter to change cart items to move items to the Saved-For-Later area, or change Saved-For-Later (SaveForLater) items to the active cart area (MoveToCart).

Type: String

Default: None

Valid Values: MoveToCart | SaveForLater

No
AssociateTag

Specifies the Associate who is making the request. An Associate tag, also known as an Associate ID, is an automatically generated unique identifier. When you log in to the Amazon Associates website for your locale, the page that you are directed to includes a message that says "Signed in as" followed by your Associate tag.

The Associate tag that you used to create a cart must also be used on all other operations associated with the same cart.

Type: String

Default: None

Valid Value: The same Associate tag that was used in the related CartCreate request.

Constraint:

Yes
CartId

Alphanumeric token returned by CartCreate that identifies a cart.

Type: String

Default: None

Valid Values: Value returned by CartCreate.

Yes
CartItemId

Specifies an item to be modified in the cart where N is a positive integer between 1 and 10, inclusive. Up to ten items can be modified at a time.CartItemId is neither an ASIN nor an OfferListingId. It is, instead, an alphanumeric token returned by CartCreate and CartAdd. This parameter is used in conjunction with Item.N.Quantity to modify the number of items in a cart. See Item, that follows, for more information.

Type: String

Default: None

Valid Values: Value returned by CartCreate or CartAdd.

Yes
HMAC

The Hash Message Authentication Code is an encrypted alphanumeric token that is used to authenticate requests.

Type: String

Default: None

Valid Values: Value is calculated using request parameters, their values, a cryptographic function, and the Secret Key, which acts as the "key" for the function. Value returned by CartCreate.

Yes
Item Specifies the item to modify. Typical construction is Item.1.CartItemId=[ID]; Item.1.Quantity=[number]. Yes
Items Container for one or more Item objects. This is a SOAP only parameter.

Valid Value: Item

Constraint: Required and valid only for SOAP requests.

Conditional
MergeCart

This parameter is deprecated. When a customer purchases items in a remote shopping cart, the items are added to the customer’s Amazon retail shopping cart.

Deprecated
Quantity

Specifies the revised number of items that the customer would like in the cart where N is a positive integer. This parameter is used in conjunction with Item.N.CartItemId to modify the number of items in a cart. The Quantity value is matched to the Item.N.CartItemId value by the index number, N. For example, Item.1.CartItemId is associated with Item.1.Quantity.

Type: Positive integer

Type: String

Default: None

Constraint: N is a positive integer between 0 and 999, inclusive. Required with REST queries.

Conditional
ResponseGroup

Specifies the types of values to return. You can specify multiple response groups in one request by separating them with commas.

Type: String

Default: Cart

Valid Values:CartSimilarities | CartTopSellers | CartNewReleases

No

CartModify also accepts the parameters that all operations can use. For more information, see Common Request Parameters.

Response

Name Description
CartId Alphanumeric token returned by CartCreate that identifies a cart.
CartItemId Specifies an item in a cart. CartItemId is neither an ASIN nor an OfferListingId. It is, instead, an alphanumeric token returned by CartCreate and CartAdd. Child of Item.
HMAC Hash Message Authentication Code returned by CartCreate that identifies a cart. This is an encrypted alphanumeric token that is used to authenticate cart operations.
Item For REST, a prefix for CartItemId and Quantity, both of which are used to specify the item to be modified, for example, item.1.CartItemId=1234abcd, item.1.Quantity=2 changes the quantity of item 1234abcd to 2.
Items Container for Item when specifying more than one Item.
Quantity The suffix used with Item to specify the number of items to be added to the cart. See Item.

For more information about the parent elements of these tags, see the appropriate response group in Response Groups.

Examples

Increase the quantity of an item (Item.1) already in the cart and remove an item (Item.2).

Copy
http://webservices.amazon.com/onca/xml? Service=AWSECommerceService& AWSAccessKeyId=[AWS Access Key ID]& AssociateTag=[Associate ID]& Operation=CartModify& CartId=[Cart ID]& HMAC=[HMAC]& Item.1.CartItemId=[Cart Item ID]& Item.1.Quantity=10& Item.2.CartItemId=[Cart Item ID]& Item.2.Quantity=0 &Timestamp=[YYYY-MM-DDThh:mm:ssZ] &Signature=[Request Signature]

Notice that items in the cart are referred to by CartItemId, not their ASIN or OfferListingId CartItemId is returned by CartCreate, CartGet, and CartAdd. If you want to use CartModify to modify the items in a cart, you must refer to the items using their CartItemId. You use CartGet to retrieve the CartItemIds.

The response to this request is shown in Sample Response.

Move an item (Item.1) to the SaveForLater area in the cart and reduce then number of items (Item.2) to 1.

Copy
http://webservices.amazon.com/onca/xml? Service=AWSECommerceService& AWSAccessKeyId=[AWS Access Key ID]& AssociateTag=[Associate ID]& Operation=CartModify& CartId=[Cart ID]& HMAC=[HMAC]& Item.1.CartItemId=[Cart Item ID]& Item.1.Action=SaveForLater Item.2.CartItemId=[Cart Item ID]& Item.2.Quantity=1 &Timestamp=[YYYY-MM-DDThh:mm:ssZ] &Signature=[Request Signature]

Sample Response

The following XML is a snippet of the full response to the first sample request.

Copy
<CartModifyRequest> <CartId>103-8104506-5223005</CartId> <HMAC>uiFluRr5yj+GGL3SvWD1mFDyvP0=</HMAC> <Items> <Item> <CartItemId>UQIKL90WK14UD</CartItemId> <Quantity>10</Quantity> </Item> </Items> </CartModifyRequest>

Notice that the quantity of the item was changed to 10 (from 5). The rest of the CartModify request is identical to the CartCreate response.

Related Operations