> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt > Use this file to discover all available pages before exploring further. # Cart Module > Learn about the Cart Module and how to manage shopping carts, line items, and cart totals in Medusa. ## Overview The Cart Module manages shopping carts and their associated data including line items, shipping methods, addresses, and real-time total calculations. It provides the foundation for the checkout process. **Key Features:** * Cart and line item management * Real-time total calculations * Tax line and adjustment tracking * Shipping method integration * Cart completion tracking * Credit lines for store credit * Multi-currency support ## When to Use Use the Cart Module when you need to: * Create and manage shopping carts * Add/remove products to carts * Calculate cart totals with taxes and discounts * Track shipping methods and costs * Store customer shipping and billing addresses * Handle cart-to-order conversion * Support guest and registered customer carts ## Data Models ### Cart The core cart entity representing a shopping session. Unique cart identifier (prefix: `cart_`) ID of the associated region ID of the customer (null for guest carts) ID of the sales channel Customer email address Three-letter ISO currency code BCP 47 language tag (e.g., "en-US") Timestamp when cart was completed (converted to order) Products added to the cart Shipping address for the cart Billing address for the cart Selected shipping methods Store credit applied to the cart ### LineItem Represents a product in the cart. Unique line item identifier ID of the parent cart Product title Product subtitle or variant title Product thumbnail URL Item quantity ID of the product ID of the product variant Price per unit before discounts Whether discounts can be applied Whether price includes tax Tax lines applied to this item Discount adjustments applied to this item Additional custom data ### ShippingMethod Represents a shipping option for the cart. Unique shipping method identifier ID of the parent cart Shipping method name Shipping cost before discounts Whether amount includes tax Reference to the fulfillment shipping option Provider-specific data Tax lines applied to shipping Discount adjustments applied to shipping ### Address Shipping or billing address for the cart. Unique address identifier Associated customer ID First name Last name Phone number Company name Address line 1 Address line 2 City Two-letter ISO country code State or province Postal/ZIP code ## Calculated Totals The Cart Module automatically calculates totals when specific fields are requested. These are not stored but computed on-demand: Final cart total after all adjustments and taxes Sum of line item subtotals before shipping Total tax amount Total discount amount Total shipping cost after discounts and taxes Sum of all line item totals Total tax on line items Total tax on shipping ## Service Interface The Cart Module service is available at `@medusajs/medusa/cart`. ### Retrieve Cart Retrieve a single cart with totals. ```typescript Example theme={null} import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" import { ICartModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" export async function GET( req: MedusaRequest, res: MedusaResponse ) { const cartModuleService: ICartModuleService = req.scope.resolve( Modules.CART ) const cart = await cartModuleService.retrieveCart("cart_123", { select: [ "id", "email", "currency_code", "total", "subtotal", "tax_total", ], relations: [ "items", "items.tax_lines", "items.adjustments", "shipping_methods", "shipping_address", ], }) res.json({ cart }) } ``` The ID of the cart to retrieve Configuration for the query Fields to select (include total fields to calculate them) Relations to load. Required relations for totals: `items`, `items.tax_lines`, `items.adjustments`, `shipping_methods`, `shipping_methods.tax_lines`, `shipping_methods.adjustments` The retrieved cart with calculated totals ### List Carts List carts with filtering. ```typescript Example theme={null} const carts = await cartModuleService.listCarts( { customer_id: "cus_123", completed_at: null, }, { relations: ["items"], take: 10, } ) ``` Filters to apply Filter by cart IDs Filter by customer IDs Filter by sales channel IDs Filter by email Filter by completion status (null for active carts) ### Create Carts Create a new shopping cart. ```typescript Example theme={null} const cart = await cartModuleService.createCarts({ region_id: "reg_us", customer_id: "cus_123", email: "customer@example.com", currency_code: "usd", sales_channel_id: "sc_web", items: [ { title: "Medusa T-Shirt", subtitle: "Size: Large", product_id: "prod_123", variant_id: "variant_456", quantity: 2, unit_price: 2000, }, ], }) ``` Cart data to create ID of the region ID of the customer (omit for guest cart) Customer email Three-letter ISO currency code ID of the sales channel Initial line items The created cart(s) ### Update Carts Update cart information. ```typescript Example theme={null} const cart = await cartModuleService.updateCarts("cart_123", { email: "newemail@example.com", region_id: "reg_eu", currency_code: "eur", }) ``` The ID of the cart to update Cart data to update ### Create Line Items Add products to a cart. ```typescript Example theme={null} const lineItem = await cartModuleService.createLineItems({ cart_id: "cart_123", title: "Medusa Hoodie", subtitle: "Size: Medium, Color: Black", product_id: "prod_789", variant_id: "variant_101", quantity: 1, unit_price: 5000, }) ``` Line item data ID of the cart Product title ID of the product ID of the product variant Item quantity Price per unit ### Update Line Items Update cart line items (e.g., change quantity). ```typescript Example theme={null} const lineItem = await cartModuleService.updateLineItems("item_123", { quantity: 3, }) ``` ### Delete Line Items Remove items from the cart. ```typescript Example theme={null} await cartModuleService.deleteLineItems(["item_123", "item_456"]) ``` ### Create Shipping Methods Add shipping method to cart. ```typescript Example theme={null} const shippingMethod = await cartModuleService.createShippingMethods({ cart_id: "cart_123", name: "Standard Shipping", amount: 500, shipping_option_id: "so_standard", }) ``` Shipping method data ID of the cart Shipping method name Shipping cost Reference to fulfillment shipping option ### Add Addresses Set shipping and billing addresses. ```typescript Example theme={null} const cart = await cartModuleService.updateCarts("cart_123", { shipping_address: { first_name: "John", last_name: "Doe", address_1: "123 Main St", city: "New York", country_code: "us", postal_code: "10001", }, billing_address: { first_name: "John", last_name: "Doe", address_1: "456 Billing Ave", city: "New York", country_code: "us", postal_code: "10002", }, }) ``` ## Integration Examples ### With Product Module Add products to cart by retrieving product data. ```typescript Example theme={null} import { Modules } from "@medusajs/framework/utils" const productModule = container.resolve(Modules.PRODUCT) const cartModule = container.resolve(Modules.CART) // Retrieve product with variant const product = await productModule.retrieveProduct("prod_123", { relations: ["variants"], }) const variant = product.variants[0] // Add to cart await cartModule.createLineItems({ cart_id: "cart_123", title: product.title, subtitle: variant.title, product_id: product.id, variant_id: variant.id, quantity: 1, unit_price: 2000, // From pricing module }) ``` ### With Pricing Module Calculate prices before adding to cart. ```typescript Example theme={null} import { Modules } from "@medusajs/framework/utils" const pricingModule = container.resolve(Modules.PRICING) // Calculate price for variant const priceSet = await pricingModule.calculatePrices( { id: ["variant_456"] }, { context: { currency_code: "usd", region_id: "reg_us", }, } ) const price = priceSet[0].calculated_amount // Add to cart with calculated price await cartModule.createLineItems({ cart_id: "cart_123", variant_id: "variant_456", quantity: 1, unit_price: price, // ... }) ``` ### With Promotion Module Apply promotions as adjustments. ```typescript Example theme={null} import { Modules } from "@medusajs/framework/utils" const promotionModule = container.resolve(Modules.PROMOTION) // Compute promotions const promotions = await promotionModule.computeActions( ["promo_123"], { items: cart.items, } ) // Apply as line item adjustments for (const action of promotions.actions) { await cartModule.createLineItemAdjustments({ item_id: action.item_id, amount: -action.amount, code: action.code, }) } ``` ### With Tax Module Calculate and apply tax lines. ```typescript Example theme={null} import { Modules } from "@medusajs/framework/utils" const taxModule = container.resolve(Modules.TAX) // Calculate taxes const taxLines = await taxModule.getTaxLines( cart.items, { address: cart.shipping_address, } ) // Apply tax lines to items for (const taxLine of taxLines) { await cartModule.createLineItemTaxLines({ item_id: taxLine.item_id, rate: taxLine.rate, code: taxLine.code, name: taxLine.name, }) } ``` ### Converting to Order Mark cart as completed and create order. ```typescript Example theme={null} import { Modules } from "@medusajs/framework/utils" const orderModule = container.resolve(Modules.ORDER) // Create order from cart const order = await orderModule.createOrders({ customer_id: cart.customer_id, email: cart.email, currency_code: cart.currency_code, items: cart.items, shipping_address: cart.shipping_address, billing_address: cart.billing_address, shipping_methods: cart.shipping_methods, }) // Mark cart as completed await cartModule.updateCarts(cart.id, { completed_at: new Date(), }) ``` ## Best Practices 1. **Total Calculation**: To calculate totals, you must include total fields in `select` and required relations (`items`, `items.tax_lines`, `items.adjustments`, `shipping_methods`, etc.). The module automatically includes needed relations when total fields are selected. 2. **Currency Consistency**: Ensure all prices (line items, shipping, adjustments) use the same currency as the cart. 3. **Guest Carts**: For guest carts, omit `customer_id` but always include `email` for order conversion. 4. **Cart Completion**: Set `completed_at` when converting to an order to prevent reuse. 5. **Adjustments**: Use negative amounts for discounts in LineItemAdjustment and ShippingMethodAdjustment. 6. **Tax-Inclusive Pricing**: Use the `is_tax_inclusive` flag to indicate if prices already include tax. ## Related Modules * [Product Module](/modules/product) - Retrieve products for cart * [Pricing Module](/modules/pricing) - Calculate product prices * [Promotion Module](/modules/promotion) - Apply discounts * [Order Module](/modules/order) - Convert carts to orders * [Region Module](/modules/region) - Region-based cart configuration