> ## Documentation Index > Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Cart > 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 fulfillment options, 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. **Key Features Covered:** * **Explicit Cart Creation:** Carts must be created before items can be added. * **Persistent Carts:** Carts are tied to the user. * **Item Management:** Add, update quantity, or remove products and variants *to an existing cart*. * **Pricing Calculation:** Automatically calculates subtotals, taxes, shipping, and grand totals. * **Discount Application:** Apply coupon codes, automatic promotions, loyalty points, and store credit. * **Address Management:** Set billing and shipping addresses for checkout calculation. * **Fulfillment Options:** Fetch fulfillment options and update fulfillment preferences per shipment. * **User Association:** Carts link to anonymous or logged-in users; retrievable via `user_id` for both. ## Core Concepts * **Creation:** A cart **must always be explicitly created** using `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 an empty cart via the API initially. * **Association:** Every cart is linked to a user automatically upon creation. * **Retrieval:** You can retrieve a specific cart using its `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. * **Persistence:** Carts persist across sessions as long as the user context (`user_id`) remains the same. * **Expiration:** Carts have an `expires_at` timestamp. Inactive carts may be cleaned up after this time. Active interaction typically extends the expiry. * **Transition to Order:** The final state of the cart (identified by its `id`) is used as the basis for creating an order via the `POST /orders` endpoint. -When an anonymous user creates a cart and then goes on to login, if the user happens to be a returning user, the currently active cart is merged into the logged in user's ID. This ensures seamless checkout experience. -Note that if the logged in user already had a different cart associated from a previous session, that cart will be marked as inactive when they login with an active cart. This is to prevent cart/item conflicts or items suddenly appearing/disappearing from the user's cart. * `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. * **Pricing Summary:** * `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` + `handling_charge_tax_amount`. * `grand_total`: The final amount after all deductions, including taxes but before loyalty points are redeemed. * **Discounts & Redemptions:** * `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 amount to display at checkout.** This is what the customer actually pays (`grand_total` - `loyalty_points_redeemed_value` - `credit_balance_used`). Always display `to_be_paid` rather than `grand_total` as the final price — it accounts for loyalty points and credit balance deductions. * **Addresses:** * `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. * `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. ## Cart API Endpoints **Explicitly creates a new cart.** This endpoint **requires** at least one item in the `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. * **Authentication:** Bearer Token (Anonymous or Logged-in) * **Request Body (Required):** *(See `UpdateCartItem` schema)* ```json Create Cart Request Body theme={"theme":{"light":"github-light","dark":"github-dark"}} { "items": [ { "product_id": "PROD_ID_1", "variant_id": "VARIANT_ID_A", // or null if no variants "quantity": 1 } // Potentially more items ] } ``` * **Response:** `200 OK` with the newly created `Cart` object, including its unique `id`. Store this `id` for subsequent cart operations. Fetches the details of a specific cart using its ID. * **Authentication:** Bearer Token (Must match the user associated with the cart ID) * **Path Parameter:** `id` (Cart ID obtained from `POST /carts` or a previous cart state) * **Response:** `200 OK` with the `Cart` object, or `404 Not Found`. Removes all items from the specified cart, effectively emptying it but leaving the cart shell intact until expiration/cleanup. * **Authentication:** Bearer Token (Must match the user associated with the cart ID) * **Path Parameter:** `id` (Cart ID) * **Response:** `200 OK` with success message, or `404 Not Found`. Fetches the active cart associated with a specific user ID. **This works for both anonymous and logged-in users.** Use the `user_id` from the user object obtained via `/auth/anonymous` or login flows. * **Authentication:** Bearer Token (Token must correspond to the user session associated with `{user_id}`) * **Path Parameter:** `user_id` * **Response:** `200 OK` with the `Cart` object, or `404 Not Found` if no active cart exists for the user. Removes all items from the active cart associated with the specified user ID (anonymous or logged-in). * **Authentication:** Bearer Token (Token must correspond to the user session associated with `{user_id}`) * **Path Parameter:** `user_id` * **Response:** `200 OK` with success message, or `404 Not Found`. Updates the contents of an **existing cart**. This endpoint **cannot** create a cart; use `POST /carts` for initial creation. * **Authentication:** Bearer Token (Must match the user associated with the cart ID) * **Path Parameter:** `id` (**Required** Cart ID obtained from `POST /carts` or `GET` requests) * **Request Body:** `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. * **Response:** `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. ```json Add/Update/Remove Item Request Body theme={"theme":{"light":"github-light","dark":"github-dark"}} { "product_id": "PROD_ID_B", "variant_id": null, "quantity": 2 // Set to 0 to remove } ``` Sets or updates the billing and shipping addresses for the cart. Crucial for calculating shipping costs and taxes. * **Authentication:** Bearer Token * **Path Parameter:** `id` (Cart ID) * **Request Body:** `oneOf` saved address IDs (logged-in users) or full `CustomerAddress` objects (guests or new address). *(Schema details unchanged)* * **Response:** `200 OK` with the updated `Cart` object. Applies a coupon code to the cart. * **Authentication:** Bearer Token * **Path Parameter:** `id` (Cart ID) * **Request Body:** ```json Apply Coupon Request Body theme={"theme":{"light":"github-light","dark":"github-dark"}} { "coupon_code": "YOUR_COUPON_CODE" } ``` * **Response:** `200 OK` with the updated `Cart` object, or `400 Bad Request`. **Important Note** If a coupon has rules like "valid for first-time customers only," attempting to apply it while the user is anonymous *may* result in a `400 Bad Request` error, potentially with a message indicating login is required. Consider prompting users to log in before applying coupons with such restrictions. Removes any currently applied coupon from the cart. * **Authentication:** Bearer Token * **Path Parameter:** `id` (Cart ID) * **Response:** `200 OK` with the updated `Cart` object. *(Endpoints `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.)* *(Endpoints `GET /wishlist/{user_id}`, `POST /wishlist/{user_id}`, `DELETE /wishlist/{user_id}` remain functionally the same, requiring a **logged-in user's** token.)* ## Common Use Cases & Flows