The Carts module provides the APIs to manage a userβs shopping cart. It allows you to add, update, and remove items, apply discounts and loyalty points, manage addresses, and retrieve the cartβs state before checkout. Commerce Engine carts are persistent and associated with the user (anonymous or logged-in), enabling seamless experiences across sessions or devices.
user_id
for both.Cart Lifecycle & Persistence
POST /carts
before any items can be added. This endpoint requires at least one item to be included in the request body for successful cart creation. There is no concept of creating a truly empty cart via the API initially.access_token
.id
(GET /carts/{id}
) or retrieve the active cart associated with a user (both anonymous and logged-in) via their user_id
(GET /carts/users/{user_id}
). This allows fetching the correct cart even if the client loses the cart_id
but still has the userβs token/ID.user_id
) remains the same.expires_at
timestamp. Inactive carts may be cleaned up after this time. Active interaction typically extends the expiry.id
) is used as the basis for creating an order via the POST /orders
endpoint.Cart Structure (Cart Object)
id
: The unique identifier for this cart.active
: Boolean indicating if the cart is still active.cart_items
: An array of CartItem
objects detailing each product/variant in the cart.cart_items_count
: Total number of unique line items.subtotal
: Sum of item selling prices (before tax and discounts).items_tax_amount
: Total tax calculated on items.subtotal_including_tax
: Subtotal + Item Tax.shipping_amount
: Calculated shipping cost (before tax).shipping_tax_amount
: Tax on shipping.shipping_amount_including_tax
: Shipping + Shipping Tax.total_tax
: items_tax_amount
+ shipping_tax_amount
.grand_total
: The final amount before user-specific deductions (subtotal_including_tax
+ shipping_amount_including_tax
- discounts).is_promotion_applied
, promotion_discount_amount
: For automatic promotions.is_coupon_applied
, coupon_code
, coupon_discount_amount
: For user-applied coupons.loyalty_points_redeemed
: Points applied as discount.loyalty_points_earned
: Points the user will earn if this cart becomes an order.credit_balance_used
: Store credit/wallet balance applied.to_be_paid
: The final amount the customer needs to pay (grand_total
- loyalty_points_redeemed_value
- credit_balance_used
).billing_address
: CustomerAddress
object.shipping_address
: CustomerAddress
object.customer_email
, customer_phone
, customer_note
: User details associated with the cart.currency
: Currency details (code
, symbol
, name
).metadata
: Custom key-value pairs.expires_at
: Timestamp when the cart might expire if inactive.Cart Items (CartItem Object)
product_id
, variant_id
, sku
: Identifiers for the item.product_name
, variant_name
, product_image_url
: Display details.quantity
: The number of this item in the cart.stock_available
, on_offer
, on_promotion
, on_subscription
: Status flags.listing_price
, selling_price
: Per-unit prices.promotion_discount_amount
, coupon_discount_amount
: Discounts applied to this line item.tax_type
, tax_rate
, tax_amount
: Tax details for this line item.shipping_additional_cost
: Any per-item shipping surcharge.associated_options
: Details of selected variant options (e.g., Color: Red, Size: Large).subscriptions
: Details if this item is being added as part of a subscription plan.is_free_item
, free_quantity
: Indicates if quantity is part of a βfree goodsβ promotion.POST /carts
items
array to successfully create the cart. It cannot be used to create an empty cart. This is typically the first cart-related call when a user adds their initial item.UpdateCartItem
schema)
200 OK
with the newly created Cart
object, including its unique id
. Store this id
for subsequent cart operations.
GET /carts/{id}
id
(Cart ID obtained from POST /carts
or a previous cart state)200 OK
with the Cart
object, or 404 Not Found
.DELETE /carts/{id}
id
(Cart ID)200 OK
with success message, or 404 Not Found
.GET /carts/users/{user_id}
user_id
from the user object obtained via /auth/anonymous
or login flows.{user_id}
)user_id
200 OK
with the Cart
object, or 404 Not Found
if no active cart exists for the user.DELETE /carts/users/{user_id}
{user_id}
)user_id
200 OK
with success message, or 404 Not Found
.POST /carts/{id}/items
POST /carts
for initial creation.id
(Required Cart ID obtained from POST /carts
or GET
requests)
UpdateCartItem
schema:
product_id
: Required ID of the product.variant_id
: Required ID of the variant (use null
if the product has no variants).quantity
: The desired total quantity for this item in the cart.
quantity > 0
: Adds or updates the item to this quantity.quantity = 0
: Removes the item from the cart.200 OK
with the updated Cart
object reflecting the changes and recalculated totals. Returns 400 Bad Request
if quantity exceeds stock or validation fails, or 404 Not Found
if the Cart ID is invalid.
POST /carts/{id}/address
id
(Cart ID)oneOf
saved address IDs (logged-in users) or full CustomerAddress
objects (guests or new address). (Schema details unchanged)200 OK
with the updated Cart
object.POST /carts/{id}/coupon
id
(Cart ID)200 OK
with the updated Cart
object, or 400 Bad Request
.400 Bad Request
error, potentially with a message indicating login is required. Consider prompting users to log in before applying coupons with such restrictions.DELETE /carts/{id}/coupon
id
(Cart ID)200 OK
with the updated Cart
object.Redeem/Remove Loyalty Points & Credit Balance
POST /carts/{id}/loyalty-points
, DELETE /carts/{id}/loyalty-points
, POST /carts/{id}/credit-balance
, DELETE /carts/{id}/credit-balance
remain functionally the same, requiring a logged-in userβs token.)Wishlist Endpoints
GET /wishlist/{user_id}
, POST /wishlist/{user_id}
, DELETE /wishlist/{user_id}
remain functionally the same, requiring a logged-in userβs token.)Adding the First Item to the Cart
Adding Subsequent Items / Updating Quantity / Removing
Retrieving Cart on Page Load / After Login