CartModify
Description
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, and 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
| 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 |
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. Type: String Default: None Valid Values: Value returned by CartCreate or
|
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 |
ListItemId
|
The Type: String Default: None Valid Values: An alphanumeric identity returned by the ListItems response group. |
No |
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
|
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 parameter is invalid but the request behaves as though the value were set to True. Type: Boolean Default:False (in US) Valid Values: True | 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 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).
http://ecs.amazonaws.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
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& 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
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.
Sample Response
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.