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. 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 Type: Positive integer Type: String Default: None Constraint: N is a positive integer between 0 and 10*, 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://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.
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.
<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
* New applicants are limited to maximum value of 1 for quantity field. Once your application is fully accepted into the Associates Program this restriction will be removed.
