Overview
Manage individual items in the shopping cart. This endpoint supports updating item quantities and removing items from the cart.
Update Item Quantity
Update the quantity of an existing item in the cart. The quantity parameter is additive - it will be added to the current quantity.
Request
Unique identifier for the cart item (format: prod{id}_{sku}_dflt)
Quantity change to apply (positive to increase, negative to decrease). Minimum value: 1
curl -X PUT https://api.example.com/api/v1/cart/items/ \
-H "Content-Type: application/json" \
-H "Cookie: sessionid=your_session_id" \
-d '{
"item_key": "prod123_SKU789_dflt",
"quantity": 2
}'
Response
Whether the update operation succeeded
Status message describing the result
{
"success": true,
"message": "Quantity updated"
}
Response - Stock Limited
If the requested quantity exceeds available stock, the quantity will be capped at the maximum available:
{
"success": true,
"message": "Quantity limited to available stock: (5)"
}
Response - Item Removed
If the quantity adjustment results in zero or negative quantity, the item is removed:
{
"success": true,
"message": "Item removed from cart"
}
Error Responses
400 Bad Request - Invalid Item Key
{
"item_key": ["Invalid cart item key"]
}
400 Bad Request - Product Unavailable
{
"item_key": ["Product is no longer availabe"]
}
400 Bad Request - Insufficient Stock
{
"quantity": ["Requested quantity: (10) exceeds available stock: (5) for this variant"]
}
400 Bad Request - Variant Removed
{
"item_key": ["Product variant no longer exists"]
}
Remove Item from Cart
Permanently remove an item from the shopping cart.
Request
Unique identifier for the cart item to remove
curl -X DELETE https://api.example.com/api/v1/cart/items/ \
-H "Content-Type: application/json" \
-H "Cookie: sessionid=your_session_id" \
-d '{
"item_key": "prod123_SKU789_dflt"
}'
Response
Whether the remove operation succeeded
Status message describing the result
{
"success": true,
"message": "Item has been removed from cart"
}
Error Responses
404 Not Found - Item Not in Cart
{
"success": false,
"message": "This item is not in your cart"
}
400 Bad Request - Invalid Item Key
{
"item_key": ["Invalid cart item key"]
}
Validation Rules
Item Key Validation
- Must exist in the current cart session
- Format:
prod{product_id}_{variant_sku}_dflt
- Case-sensitive
Quantity Updates
- Minimum quantity: 1
- Automatically capped at available stock level
- If resulting quantity is less than or equal to 0, item is removed
- Stock validation occurs in real-time
Product Availability
- Product variant must be active
- Product variant must exist in database
- If unavailable, item is automatically removed with appropriate message
Automatic Price Updates
When updating cart items, the following are automatically recalculated:
- Current product price (reflects any active offers)
- Offer eligibility and status
- Voucher discount amounts (if applicable)
- Cart totals
- To add new items to cart, use
POST /api/v1/cart/
- To view cart contents, use
GET /api/v1/cart/
- To clear entire cart, use
DELETE /api/v1/cart/