Cart

Store API endpoints for creating and managing shopping carts.

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": "[e-mail]"
  }'

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