Add a product to the shopping cart by specifying the variant SKU and desired quantity. The cart automatically applies any eligible offers and calculates pricing with discounts.
Authentication
Not required - cart is session-based
Request Body
The SKU of the product variant to add (e.g., “2f23232242f2f3f”)
Number of units to add. Must be positive.
Response
Returns a success message with the updated cart total:
Confirmation message describing what was added
Updated total value of the entire cart after adding this item
Example Request
curl -X POST http://localhost:8000/api/v1/cart/ \
-H "Content-Type: application/json" \
-H "Cookie: sessionid=your_session_id" \
-d '{
"variant_sku": "2f23232242f2f3f",
"quantity": 2
}'
import requests
url = "http://localhost:8000/api/v1/cart/"
headers = {
"Content-Type": "application/json"
}
cookies = {
"sessionid": "your_session_id"
}
data = {
"variant_sku": "2f23232242f2f3f",
"quantity": 2
}
response = requests.post(url, headers=headers, cookies=cookies, json=data)
print(response.json())
const response = await fetch('http://localhost:8000/api/v1/cart/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
credentials: 'include', // Include session cookie
body: JSON.stringify({
variant_sku: '2f23232242f2f3f',
quantity: 2
})
});
const data = await response.json();
console.log(data);
Example Response
{
"success": "2x Wireless Headphones - Black has been added",
"cart_total": 192.97
}
Error Responses
400 Bad Request
Returned when required fields are missing or invalid:
{
"variant_sku": ["This field is required."],
"quantity": ["Ensure this value is greater than or equal to 1."]
}
404 Not Found
Returned when the variant SKU doesn’t exist or is inactive:
{
"variant": ["Product variant not found or is no longer available."]
}
400 Insufficient Stock
Returned when requested quantity exceeds available stock:
{
"quantity": ["Only 3 units available in stock."]
}
How Adding Works
When you add an item to the cart:
Variant Validation
The system validates the variant exists, is active, and has sufficient stock
Duplicate Check
If the same variant already exists in cart, quantities are merged
Offer Application
Eligible automatic offers are applied to calculate discounted pricing
Cart Update
Item is added/updated in the session cart with current pricing
Total Calculation
Cart totals are recalculated including shipping and all discounts
Automatic Features
Offer Application
When adding items, the system automatically:
- Checks for active product-level offers
- Validates offer conditions (customer eligibility, time windows)
- Applies the best available discount
- Stores offer information with the cart item
Stock Validation
The cart ensures:
- Variant is currently active and available
- Requested quantity doesn’t exceed stock level
- If item already in cart, combined quantity is within stock limits
Price Locking
When added to cart:
- Current price is captured at add time
- Original price (before offers) is stored for comparison
- Prices are refreshed every 5 minutes to reflect current offers
- Expired offers are automatically removed on refresh
Session Management
The shopping cart is session-based:
- No authentication required to add items
- Session cookie (
sessionid) is automatically created
- Cart data persists for 30 minutes of inactivity
- Adding items refreshes the session timeout
If a customer logs in after adding items to their cart, the session cart is preserved and can be converted to an order upon checkout.
Business Rules
- Minimum quantity: 1 unit
- Maximum quantity: Limited by available stock for that variant
- Duplicate items: Quantities are combined (not separate line items)
- Inactive variants: Cannot be added to cart
- Stock validation: Performed at add time and during cart refresh
For updating quantities of items already in the cart, use the Update Cart Items endpoint instead. Code Reference
Implementation: ~/workspace/source/cart/views.py:65-79