Cart Module

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.

string

required

Unique cart identifier (prefix: cart_)

string

ID of the associated region

string

ID of the customer (null for guest carts)

string

ID of the sales channel

string

Customer email address

string

required

Three-letter ISO currency code

string

BCP 47 language tag (e.g., “en-US”)

DateTime

Timestamp when cart was completed (converted to order)

LineItem[]

Products added to the cart

Address

Shipping address for the cart

Address

Billing address for the cart

ShippingMethod[]

Selected shipping methods

CreditLine[]

Store credit applied to the cart

LineItem

Represents a product in the cart.

string

required

Unique line item identifier

string

required

ID of the parent cart

string

required

Product title

string

Product subtitle or variant title

string

Product thumbnail URL

number

required

Item quantity

string

ID of the product

string

ID of the product variant

BigNumber

required

Price per unit before discounts

boolean

Whether discounts can be applied

boolean

Whether price includes tax

LineItemTaxLine[]

Tax lines applied to this item

LineItemAdjustment[]

Discount adjustments applied to this item

object

Additional custom data

ShippingMethod

Represents a shipping option for the cart.

string

required

Unique shipping method identifier

string

required

ID of the parent cart

string

required

Shipping method name

BigNumber

required

Shipping cost before discounts

boolean

Whether amount includes tax

string

Reference to the fulfillment shipping option

object

Provider-specific data

ShippingMethodTaxLine[]

Tax lines applied to shipping

ShippingMethodAdjustment[]

Discount adjustments applied to shipping

Address

Shipping or billing address for the cart.

string

required

Unique address identifier

string

Associated customer ID

string

First name

string

Last name

string

Phone number

string

Company name

string

Address line 1

string

Address line 2

string

City

string

Two-letter ISO country code

string

State or province

string

Postal/ZIP code

Calculated Totals

The Cart Module automatically calculates totals when specific fields are requested. These are not stored but computed on-demand:

BigNumber

Final cart total after all adjustments and taxes

BigNumber

Sum of line item subtotals before shipping

BigNumber

Total tax amount

BigNumber

Total discount amount

BigNumber

Total shipping cost after discounts and taxes

BigNumber

Sum of all line item totals

BigNumber

Total tax on line items

BigNumber

Total tax on shipping

Service Interface

The Cart Module service is available at @medusajs/medusa/cart.

Retrieve Cart

Retrieve a single cart with totals.

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 })
}

string

required

The ID of the cart to retrieve

FindConfig

Configuration for the query

string[]

Fields to select (include total fields to calculate them)

string[]

Relations to load. Required relations for totals: items, items.tax_lines, items.adjustments, shipping_methods, shipping_methods.tax_lines, shipping_methods.adjustments

CartDTO

The retrieved cart with calculated totals

List Carts

List carts with filtering.

const carts = await cartModuleService.listCarts(
  {
    customer_id: "cus_123",
    completed_at: null,
  },
  {
    relations: ["items"],
    take: 10,
  }
)

FilterableCartProps

Filters to apply

string | string[]

Filter by cart IDs

string | string[]

Filter by customer IDs

string | string[]

Filter by sales channel IDs

string

Filter by email

null | object

Filter by completion status (null for active carts)

Create Carts

Create a new shopping cart.

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,
    },
  ],
})

CreateCartDTO | CreateCartDTO[]

required

Cart data to create

string

ID of the region

string

ID of the customer (omit for guest cart)

string

Customer email

string

required

Three-letter ISO currency code

string

ID of the sales channel

CreateLineItemDTO[]

Initial line items

CartDTO | CartDTO[]

The created cart(s)

Update Carts

Update cart information.

const cart = await cartModuleService.updateCarts("cart_123", {
  email: "newemail@example.com",
  region_id: "reg_eu",
  currency_code: "eur",
})

string

required

The ID of the cart to update

UpdateCartDTO

required

Cart data to update

Create Line Items

Add products to a cart.

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,
})

CreateLineItemDTO | CreateLineItemDTO[]

required

Line item data

string

required

ID of the cart

string

required

Product title

string

ID of the product

string

ID of the product variant

number

required

Item quantity

number

required

Price per unit

Update Line Items

Update cart line items (e.g., change quantity).

const lineItem = await cartModuleService.updateLineItems("item_123", {
  quantity: 3,
})

Delete Line Items

Remove items from the cart.

await cartModuleService.deleteLineItems(["item_123", "item_456"])

Create Shipping Methods

Add shipping method to cart.

const shippingMethod = await cartModuleService.createShippingMethods({
  cart_id: "cart_123",
  name: "Standard Shipping",
  amount: 500,
  shipping_option_id: "so_standard",
})

CreateShippingMethodDTO | CreateShippingMethodDTO[]

required

Shipping method data

string

required

ID of the cart

string

required

Shipping method name

number

required

Shipping cost

string

Reference to fulfillment shipping option

Add Addresses

Set shipping and billing addresses.

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.

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.

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.

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.

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.

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

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.
Currency Consistency: Ensure all prices (line items, shipping, adjustments) use the same currency as the cart.
Guest Carts: For guest carts, omit customer_id but always include email for order conversion.
Cart Completion: Set completed_at when converting to an order to prevent reuse.
Adjustments: Use negative amounts for discounts in LineItemAdjustment and ShippingMethodAdjustment.
Tax-Inclusive Pricing: Use the is_tax_inclusive flag to indicate if prices already include tax.

Product Module - Retrieve products for cart
Pricing Module - Calculate product prices
Promotion Module - Apply discounts
Order Module - Convert carts to orders
Region Module - Region-based cart configuration

Get Started

Core Concepts

Commerce Modules

Building with Medusa

Providers

Admin Dashboard

Deployment

Overview

When to Use

Data Models

Cart

LineItem

ShippingMethod

Address

Calculated Totals

Service Interface

Retrieve Cart

List Carts

Create Carts

Update Carts

Create Line Items

Update Line Items

Delete Line Items

Create Shipping Methods

Add Addresses

Integration Examples

With Product Module

With Pricing Module

With Promotion Module

With Tax Module

Converting to Order

Best Practices

​Overview

​When to Use

​Data Models

​Cart

​LineItem

​ShippingMethod

​Address

​Calculated Totals

​Service Interface

​Retrieve Cart

​List Carts

​Create Carts

​Update Carts

​Create Line Items

​Update Line Items

​Delete Line Items

​Create Shipping Methods

​Add Addresses

​Integration Examples

​With Product Module

​With Pricing Module

​With Promotion Module

​With Tax Module

​Converting to Order

​Best Practices

​Related Modules

Overview

When to Use

Data Models

Cart

LineItem

ShippingMethod

Address

Calculated Totals

Service Interface

Retrieve Cart

List Carts

Create Carts

Update Carts

Create Line Items

Update Line Items

Delete Line Items

Create Shipping Methods

Add Addresses

Integration Examples

With Product Module

With Pricing Module

With Promotion Module

With Tax Module

Converting to Order

Best Practices

Related Modules