Skip to main content

​
Overview

The Cart API enables customers to create shopping carts, add/remove items, apply promotions, and manage shipping information before completing checkout. Base Path: /store/carts Source: packages/medusa/src/api/store/carts/route.ts

​
Create Cart

Create a new shopping cart. 
POST /store/carts

​
Request Body

​
region_id
string
The region where the cart is used. Determines available shipping options and tax rates.
​
sales_channel_id
string
The sales channel for the cart.
​
currency_code
string
Currency code for the cart (e.g., “usd”).
​
email
string
Customer’s email address.
​
metadata
object
Custom metadata key-value pairs.

​
Request

curl -X POST http://localhost:9000/store/carts \
  -H "Content-Type: application/json" \
  -d '{
    "region_id": "reg_us",
    "currency_code": "usd"
  }'

​
Response

{
  "cart": {
    "id": "cart_123",
    "region_id": "reg_us",
    "currency_code": "usd",
    "email": null,
    "items": [],
    "shipping_address": null,
    "billing_address": null,
    "shipping_methods": [],
    "payment_collection": null,
    "subtotal": 0,
    "discount_total": 0,
    "shipping_total": 0,
    "tax_total": 0,
    "total": 0,
    "created_at": "2024-03-03T10:00:00.000Z"
  }
}
​
cart
object
The created cart object.
Source: packages/medusa/src/api/store/carts/route.ts:13
If the customer is authenticated, the cart is automatically associated with their account via req.auth_context.actor_id (see line 22).

​
Get Cart

Retrieve a cart by ID. 
GET /store/carts/{id}

​
Path Parameters

​
id
string
required
The cart’s ID.

​
Request

curl -X GET http://localhost:9000/store/carts/cart_123

​
Response

{
  "cart": {
    "id": "cart_123",
    "region_id": "reg_us",
    "items": [...],
    "shipping_address": {...},
    "total": 5998
  }
}
Source: packages/medusa/src/api/store/carts/[id]/route.ts

​
Update Cart

Update cart details such as email or region. 
POST /store/carts/{id}

​
Path Parameters

​
id
string
required
The cart’s ID.

​
Request Body

​
email
string
Update the customer’s email.
​
region_id
string
Change the cart’s region.
​
currency_code
string
Change the currency.
​
metadata
object
Update metadata.

​
Request

curl -X POST http://localhost:9000/store/carts/cart_123 \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

​
Line Items

​
Add Line Item

Add a product variant to the cart. 
POST /store/carts/{id}/line-items

​
Path Parameters

​
id
string
required
The cart’s ID.

​
Request Body

​
variant_id
string
required
The product variant ID to add.
​
quantity
number
required
Quantity to add.
​
metadata
object
Custom metadata for the line item.

​
Request

curl -X POST http://localhost:9000/store/carts/cart_123/line-items \
  -H "Content-Type: application/json" \
  -d '{
    "variant_id": "variant_456",
    "quantity": 2
  }'

​
Response

{
  "cart": {
    "id": "cart_123",
    "items": [
      {
        "id": "item_789",
        "cart_id": "cart_123",
        "variant_id": "variant_456",
        "title": "Premium T-Shirt",
        "quantity": 2,
        "unit_price": 2999,
        "subtotal": 5998,
        "tax_total": 480,
        "total": 6478,
        "variant": {
          "id": "variant_456",
          "title": "Small / Black",
          "sku": "SHIRT-SM-BLK",
          "product": {
            "id": "prod_123",
            "title": "Premium T-Shirt",
            "thumbnail": "https://example.com/image.jpg"
          }
        }
      }
    ],
    "subtotal": 5998,
    "total": 6478
  }
}
Source: packages/medusa/src/api/store/carts/[id]/line-items/route.ts

​
Update Line Item

Update the quantity of a line item. 
POST /store/carts/{id}/line-items/{line_id}

​
Path Parameters

​
id
string
required
The cart’s ID.
​
line_id
string
required
The line item’s ID.

​
Request Body

​
quantity
number
required
New quantity for the line item.
​
metadata
object
Update metadata.

​
Request

curl -X POST http://localhost:9000/store/carts/cart_123/line-items/item_789 \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3
  }'
Source: packages/medusa/src/api/store/carts/[id]/line-items/[line_id]/route.ts

​
Delete Line Item

Remove a line item from the cart. 
DELETE /store/carts/{id}/line-items/{line_id}

​
Request

curl -X DELETE http://localhost:9000/store/carts/cart_123/line-items/item_789

​
Addresses

​
Update Shipping Address

Set or update the shipping address. 
POST /store/carts/{id}/shipping-address

​
Request Body

​
first_name
string
First name.
​
last_name
string
Last name.
​
company
string
Company name.
​
address_1
string
required
Address line 1.
​
address_2
string
Address line 2.
​
city
string
required
City.
​
province
string
State or province.
​
postal_code
string
required
Postal or ZIP code.
​
country_code
string
required
Two-letter ISO country code.
​
phone
string
Phone number.

​
Request

curl -X POST http://localhost:9000/store/carts/cart_123/shipping-address \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "123 Main St",
    "city": "New York",
    "postal_code": "10001",
    "country_code": "us"
  }'

​
Update Billing Address

Set or update the billing address. 
POST /store/carts/{id}/billing-address
Accepts the same request body as shipping address.

​
Shipping Methods

​
Add Shipping Method

Select a shipping method for the cart. 
POST /store/carts/{id}/shipping-methods

​
Request Body

​
option_id
string
required
The shipping option ID.
​
data
object
Additional data required by the shipping provider.

​
Request

curl -X POST http://localhost:9000/store/carts/cart_123/shipping-methods \
  -H "Content-Type: application/json" \
  -d '{
    "option_id": "so_standard"
  }'

​
Response

{
  "cart": {
    "id": "cart_123",
    "shipping_methods": [
      {
        "id": "sm_789",
        "shipping_option_id": "so_standard",
        "name": "Standard Shipping",
        "amount": 500,
        "tax_total": 40,
        "total": 540
      }
    ],
    "shipping_total": 500,
    "total": 6978
  }
}
Source: packages/medusa/src/api/store/carts/[id]/shipping-methods/route.ts

​
Promotions

​
Apply Promotion Code

Apply a promotion code to the cart. 
POST /store/carts/{id}/promotions

​
Request Body

​
promo_codes
string[]
required
Array of promotion codes to apply.

​
Request

curl -X POST http://localhost:9000/store/carts/cart_123/promotions \
  -H "Content-Type: application/json" \
  -d '{
    "promo_codes": ["SUMMER20"]
  }'

​
Response

{
  "cart": {
    "id": "cart_123",
    "discount_total": 1200,
    "total": 5778
  }
}
Source: packages/medusa/src/api/store/carts/[id]/promotions/route.ts

​
Remove Promotion Code

Remove a promotion code from the cart. 
DELETE /store/carts/{id}/promotions

​
Request Body

​
promo_codes
string[]
required
Array of promotion codes to remove.

​
Customer Association

​
Update Customer

Associate the cart with a customer. 
POST /store/carts/{id}/customer

​
Request Body

​
customer_id
string
The customer ID to associate.
​
email
string
Customer email if not registered.
Source: packages/medusa/src/api/store/carts/[id]/customer/route.ts

​
Calculate Taxes

Manually trigger tax calculation for the cart. 
POST /store/carts/{id}/taxes
Source: packages/medusa/src/api/store/carts/[id]/taxes/route.ts
Taxes are usually calculated automatically when the shipping address is set or updated.

​
Next Steps

Checkout

Complete the cart and create an order

Products

Browse products to add to cart

Build docs developers (and LLMs) love

Get started for freeTalk to us