CartModify

The CartModify operation enables you to:

Change the quantity of items that are already in a remote shopping cart.
Move items from the active area of a cart to the SaveForLater area or the reverse
Change the MergeCart setting.

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.

If the associated CartCreate request specified an AssociateTag, all CartModify requests must also include a value for Associate Tag otherwise the request will fail.

Availability

All locales.

Request Parameters

The following table describes the request parameters for CartModify. Parameter names are case sensitive.

Parameter	Definition	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). Default: None Valid Values: MoveToCart \| SaveForLater	No
`CartId`	Alphanumeric token returned by CartCreate that identifies a cart. 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. 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. 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
`ListItemId`	The `ListItemId` parameter is returned by the ListItems response group. The parameter identifies an item on a list, such as a wishlist. To add this item to a cart, you must include in the CartCreate request the item's ASIN and ListItemId. The ListItemId includes the name and address of the list owner, which the ASIN alone does not. Default: None Valid Values: An alphanumeric identity returned by the ListItems response group.	No
`MergeCart`	A boolean value that when True specifies that the items in a customer's remote shopping cart are added to the customer’s Amazon retail shopping cart. This occurs when the customer elects to purchase the items in their remote shopping cart. When the value is False (the default) the remote shopping cart contents are not added to the retail shopping cart. Instead, the customer is sent directly to the Order Pipeline when they elect to purchase the items in their cart. This parameter is valid only in the US locale. In all other locales, the value is always False. Type: Boolean Default:False Valid Values: True (Invalid in non-US locales) \| False	No
`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 Default: None Constraint: N is a positive integer between 0 and 999, inclusive.	Yes, with REST
`ResponseGroup`	Specifies the types of values to return. You can specify multiple response groups in one request by separating them with commas. 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

SOAP Parameters

The following additional parameters are valid in CartModify SOAP requests only.

Parameter	Definition	Required
`Item`	Container for ASIN or OfferListingId, and Quantity.	Yes
`Items`	Container for one or more Item(s).	Yes

Response Tags

The following table describes the default response tags included in CartModify responses.

Element Tag	Definition
`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

Sample Requests

Because the MergeCart value pertains to all of the items in a cart, you do not need to specify the items in the cart if all you want to do is change the value of MergeCart. Setting the value of MergeCart to “True” changes the PurchaseURL value accordingly, which means that when the customer proceeds to buying the items using the PurchaseURL, the contents of the remote shopping cart are added to Amazon’s local shopping cart, which is owned by the customer.

Use CartModify in the following ways:

Increase the quantity of an item (Item.1) already in the cart and remove an item (Item.2).
```
http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&amp;
AWSAccessKeyId=[AWS Access Key ID]&
AssociateTag=[Associate ID]&
Operation=CartModify&
CartId=[Cart ID]&
HMAC=[HMAC]&amp;
Item.1.CartItemId=[Cart Item ID]&
Item.1.Quantity=10&
Item.2.CartItemId=[Cart Item ID]&
Item.2.Quantity=0
```
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, Response to Sample Request.

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

http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&amp;
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

Change the MergeCart value to “True.”

http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
AssociateTag=[Associate ID]&
Operation=CartModify&
CartId=[Cart ID]&
HMAC=[HMAC]&
MergeCart=True

Response to Sample Request

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

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