Medusa v2 Cart and Checkout
Before writing code
Fetch live docs:
- Web-search
site:docs.medusajs.com cart module for cart data model and service methods
- Web-search
site:docs.medusajs.com checkout flow for the end-to-end checkout process
- Web-search
site:docs.medusajs.com sales channel for sales channel scoping
- Fetch
https://docs.medusajs.com/resources/references/cart and review the ICartModuleService interface
- Web-search
medusajs v2 cart workflow 2026 for latest cart-related workflow steps
Cart Lifecycle
Flow
Create Cart ──> Add Line Items ──> Set Address
──> Select Shipping ──> Init Payment ──> Complete
Cart States
| State |
Description |
| Active |
Cart is open, items can be added/removed |
| Completing |
Checkout in progress, payment being processed |
| Completed |
Cart converted to order, no further modifications |
Cart Data Model
| Entity |
Key Fields |
| Cart |
region_id, customer_id, sales_channel_id, email |
| LineItems[] |
variant_id, quantity, unit_price, Adjustments[] |
| ShippingMethods[] |
shipping_option_id, amount, data |
| Addresses |
shipping_address, billing_address |
| PaymentCollection |
PaymentSessions[] |
Module Architecture
| Link Target |
Purpose |
| Product Module |
Variant resolution |
| Region Module |
Currency, tax rules |
| Sales Channel Module |
Storefront scoping |
| Promotion Module |
Discount application |
| Payment Module |
Payment sessions |
| Fulfillment Module |
Shipping methods |
Fetch live docs for cross-module link definitions and remoteQuery usage for cart enrichment.
Checkout Steps
Step 1: Create Cart
// Skeleton: create cart in storefront
// Fetch live docs for createCartWorkflow input
const cart = await createCartWorkflow(container)
.run({ input: { region_id, sales_channel_id } })
// Fetch live docs for required vs optional fields
Step 2: Add Line Items
| Workflow |
Purpose |
addToCartWorkflow |
Add variant + quantity to cart |
updateLineItemInCartWorkflow |
Update quantity of existing item |
deleteLineItemsWorkflow |
Remove items from cart |
Step 3: Set Addresses
| Field |
Required |
Notes |
first_name / last_name |
Yes |
|
address_1 |
Yes |
Street address |
city |
Yes |
|
country_code |
Yes |
ISO 2-letter code |
postal_code |
Conditional |
Required by region |
province |
Conditional |
State/province |
Step 4: Select Shipping Option
Available options determined by cart region, shipping address, and shipping profiles.
| Workflow |
Purpose |
listShippingOptionsForCartWorkflow |
Fetch available options |
addShippingMethodToCartWorkflow |
Apply selected shipping option |
Step 5: Initialize Payment
| Workflow |
Purpose |
createPaymentCollectionForCartWorkflow |
Create payment collection |
initializePaymentSessionWorkflow |
Start provider-specific session |
Step 6: Complete Cart
| Workflow |
Purpose |
completeCartWorkflow |
Convert cart to order |
Completion validates: all items in stock, shipping selected, payment authorized, email set.
Fetch live docs for the exact validation checks performed during cart completion.
Sales Channels
| Concept |
Description |
| Sales Channel |
Named storefront scope (e.g., "Web", "Mobile App", "B2B") |
| Publishable API Key |
Associates Store API requests with a sales channel |
| Product-Channel Link |
Products published to specific channels |
- Each cart belongs to one sales channel
- Store API requests must include
x-publishable-api-key header
- Products not linked to the cart's channel are unavailable
Fetch live docs for publishable API key configuration and sales channel management.
Store API Routes
| Route Pattern |
Method |
Purpose |
/store/carts |
POST |
Create cart |
/store/carts/:id |
GET |
Retrieve cart |
/store/carts/:id |
POST |
Update cart (email, address) |
/store/carts/:id/line-items |
POST |
Add line item |
/store/carts/:id/line-items/:item_id |
POST/DELETE |
Update/remove line item |
/store/carts/:id/shipping-methods |
POST |
Add shipping method |
/store/carts/:id/payment-collections |
POST |
Create payment collection |
/store/carts/:id/complete |
POST |
Complete checkout |
Fetch live docs for request body shapes and response formats on each route.
Best Practices
Cart Management
- Always create carts with a
region_id -- it determines currency, tax rules, and shipping
- Use
sales_channel_id to scope product availability per storefront
- Store custom checkout data in cart
metadata (e.g., gift messages, notes)
Checkout Flow
- Validate addresses before shipping option selection -- options depend on the destination
- Re-fetch shipping options after address changes (available options may differ)
- Initialize payment sessions only after shipping is selected (total must include shipping)
- Handle cart completion errors gracefully -- display specific validation failures to the user
Performance
- Use
remoteQuery to enrich cart data (product details, images) in a single query
- Cache shipping options per region + address combination to reduce API calls
Security
- Never expose payment session secrets to the client
- Validate cart ownership (customer or anonymous session) on every mutation
- Use publishable API keys to enforce sales channel scoping
Fetch the Medusa v2 cart module documentation and checkout workflow references for exact service method signatures, workflow inputs, and validation rules before implementing.
1---2name: medusa-cart-checkout3description: Implement Medusa v2 cart and checkout — cart lifecycle, line items, shipping and payment selection, sales channels, and checkout completion flow. Use when building cart and checkout features.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-cart-checkout7---89# Medusa v2 Cart and Checkout1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.medusajs.com cart module` for cart data model and service methods152. Web-search `site:docs.medusajs.com checkout flow` for the end-to-end checkout process163. Web-search `site:docs.medusajs.com sales channel` for sales channel scoping174. Fetch `https://docs.medusajs.com/resources/references/cart` and review the `ICartModuleService` interface185. Web-search `medusajs v2 cart workflow 2026` for latest cart-related workflow steps1920## Cart Lifecycle2122### Flow2324```25Create Cart ──> Add Line Items ──> Set Address26 ──> Select Shipping ──> Init Payment ──> Complete27```2829### Cart States3031| State | Description |32|-------|-------------|33| Active | Cart is open, items can be added/removed |34| Completing | Checkout in progress, payment being processed |35| Completed | Cart converted to order, no further modifications |3637## Cart Data Model3839| Entity | Key Fields |40|--------|------------|41| **Cart** | region_id, customer_id, sales_channel_id, email |42| **LineItems[]** | variant_id, quantity, unit_price, Adjustments[] |43| **ShippingMethods[]** | shipping_option_id, amount, data |44| **Addresses** | shipping_address, billing_address |45| **PaymentCollection** | PaymentSessions[] |4647### Module Architecture4849| Link Target | Purpose |50|-------------|---------|51| Product Module | Variant resolution |52| Region Module | Currency, tax rules |53| Sales Channel Module | Storefront scoping |54| Promotion Module | Discount application |55| Payment Module | Payment sessions |56| Fulfillment Module | Shipping methods |5758> **Fetch live docs** for cross-module link definitions and `remoteQuery` usage for cart enrichment.5960## Checkout Steps6162### Step 1: Create Cart6364```ts65// Skeleton: create cart in storefront66// Fetch live docs for createCartWorkflow input67const cart = await createCartWorkflow(container)68 .run({ input: { region_id, sales_channel_id } })69// Fetch live docs for required vs optional fields70```7172### Step 2: Add Line Items7374| Workflow | Purpose |75|----------|---------|76| `addToCartWorkflow` | Add variant + quantity to cart |77| `updateLineItemInCartWorkflow` | Update quantity of existing item |78| `deleteLineItemsWorkflow` | Remove items from cart |7980### Step 3: Set Addresses8182| Field | Required | Notes |83|-------|----------|-------|84| `first_name` / `last_name` | Yes | |85| `address_1` | Yes | Street address |86| `city` | Yes | |87| `country_code` | Yes | ISO 2-letter code |88| `postal_code` | Conditional | Required by region |89| `province` | Conditional | State/province |9091### Step 4: Select Shipping Option9293Available options determined by cart **region**, **shipping address**, and **shipping profiles**.9495| Workflow | Purpose |96|----------|---------|97| `listShippingOptionsForCartWorkflow` | Fetch available options |98| `addShippingMethodToCartWorkflow` | Apply selected shipping option |99100### Step 5: Initialize Payment101102| Workflow | Purpose |103|----------|---------|104| `createPaymentCollectionForCartWorkflow` | Create payment collection |105| `initializePaymentSessionWorkflow` | Start provider-specific session |106107### Step 6: Complete Cart108109| Workflow | Purpose |110|----------|---------|111| `completeCartWorkflow` | Convert cart to order |112113Completion validates: all items in stock, shipping selected, payment authorized, email set.114115> **Fetch live docs** for the exact validation checks performed during cart completion.116117## Sales Channels118119| Concept | Description |120|---------|-------------|121| Sales Channel | Named storefront scope (e.g., "Web", "Mobile App", "B2B") |122| Publishable API Key | Associates Store API requests with a sales channel |123| Product-Channel Link | Products published to specific channels |124125- Each cart belongs to one sales channel126- Store API requests must include `x-publishable-api-key` header127- Products not linked to the cart's channel are unavailable128129> **Fetch live docs** for publishable API key configuration and sales channel management.130131## Store API Routes132133| Route Pattern | Method | Purpose |134|---------------|--------|---------|135| `/store/carts` | POST | Create cart |136| `/store/carts/:id` | GET | Retrieve cart |137| `/store/carts/:id` | POST | Update cart (email, address) |138| `/store/carts/:id/line-items` | POST | Add line item |139| `/store/carts/:id/line-items/:item_id` | POST/DELETE | Update/remove line item |140| `/store/carts/:id/shipping-methods` | POST | Add shipping method |141| `/store/carts/:id/payment-collections` | POST | Create payment collection |142| `/store/carts/:id/complete` | POST | Complete checkout |143144> **Fetch live docs** for request body shapes and response formats on each route.145146## Best Practices147148### Cart Management149- Always create carts with a `region_id` -- it determines currency, tax rules, and shipping150- Use `sales_channel_id` to scope product availability per storefront151- Store custom checkout data in cart `metadata` (e.g., gift messages, notes)152153### Checkout Flow154- Validate addresses before shipping option selection -- options depend on the destination155- Re-fetch shipping options after address changes (available options may differ)156- Initialize payment sessions only after shipping is selected (total must include shipping)157- Handle cart completion errors gracefully -- display specific validation failures to the user158159### Performance160- Use `remoteQuery` to enrich cart data (product details, images) in a single query161- Cache shipping options per region + address combination to reduce API calls162163### Security164- Never expose payment session secrets to the client165- Validate cart ownership (customer or anonymous session) on every mutation166- Use publishable API keys to enforce sales channel scoping167168Fetch the Medusa v2 cart module documentation and checkout workflow references for exact service method signatures, workflow inputs, and validation rules before implementing.