> ## 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

> 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.

```bash theme={null}
POST /store/carts
```

### Request Body

<ParamField body="region_id" type="string">
  The region where the cart is used. Determines available shipping options and tax rates.
</ParamField>

<ParamField body="sales_channel_id" type="string">
  The sales channel for the cart.
</ParamField>

<ParamField body="currency_code" type="string">
  Currency code for the cart (e.g., "usd").
</ParamField>

<ParamField body="email" type="string">
  Customer's email address.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata key-value pairs.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "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"
  }
}
```

<ResponseField name="cart" type="object">
  The created cart object.
</ResponseField>

**Source:** `packages/medusa/src/api/store/carts/route.ts:13`

<Note>
  If the customer is authenticated, the cart is automatically associated with their account via `req.auth_context.actor_id` (see line 22).
</Note>

## Get Cart

Retrieve a cart by ID.

```bash theme={null}
GET /store/carts/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The cart's ID.
</ParamField>

### Request

```bash theme={null}
curl -X GET http://localhost:9000/store/carts/cart_123
```

### Response

```json theme={null}
{
  "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.

```bash theme={null}
POST /store/carts/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The cart's ID.
</ParamField>

### Request Body

<ParamField body="email" type="string">
  Update the customer's email.
</ParamField>

<ParamField body="region_id" type="string">
  Change the cart's region.
</ParamField>

<ParamField body="currency_code" type="string">
  Change the currency.
</ParamField>

<ParamField body="metadata" type="object">
  Update metadata.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/store/carts/cart_123 \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com"
  }'
```

## Line Items

### Add Line Item

Add a product variant to the cart.

```bash theme={null}
POST /store/carts/{id}/line-items
```

### Path Parameters

<ParamField path="id" type="string" required>
  The cart's ID.
</ParamField>

### Request Body

<ParamField body="variant_id" type="string" required>
  The product variant ID to add.
</ParamField>

<ParamField body="quantity" type="number" required>
  Quantity to add.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata for the line item.
</ParamField>

### Request

```bash theme={null}
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

```json theme={null}
{
  "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.

```bash theme={null}
POST /store/carts/{id}/line-items/{line_id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The cart's ID.
</ParamField>

<ParamField path="line_id" type="string" required>
  The line item's ID.
</ParamField>

### Request Body

<ParamField body="quantity" type="number" required>
  New quantity for the line item.
</ParamField>

<ParamField body="metadata" type="object">
  Update metadata.
</ParamField>

### Request

```bash theme={null}
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.

```bash theme={null}
DELETE /store/carts/{id}/line-items/{line_id}
```

### Request

```bash theme={null}
curl -X DELETE http://localhost:9000/store/carts/cart_123/line-items/item_789
```

## Addresses

### Update Shipping Address

Set or update the shipping address.

```bash theme={null}
POST /store/carts/{id}/shipping-address
```

### Request Body

<ParamField body="first_name" type="string">
  First name.
</ParamField>

<ParamField body="last_name" type="string">
  Last name.
</ParamField>

<ParamField body="company" type="string">
  Company name.
</ParamField>

<ParamField body="address_1" type="string" required>
  Address line 1.
</ParamField>

<ParamField body="address_2" type="string">
  Address line 2.
</ParamField>

<ParamField body="city" type="string" required>
  City.
</ParamField>

<ParamField body="province" type="string">
  State or province.
</ParamField>

<ParamField body="postal_code" type="string" required>
  Postal or ZIP code.
</ParamField>

<ParamField body="country_code" type="string" required>
  Two-letter ISO country code.
</ParamField>

<ParamField body="phone" type="string">
  Phone number.
</ParamField>

### Request

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
POST /store/carts/{id}/shipping-methods
```

### Request Body

<ParamField body="option_id" type="string" required>
  The shipping option ID.
</ParamField>

<ParamField body="data" type="object">
  Additional data required by the shipping provider.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "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.

```bash theme={null}
POST /store/carts/{id}/promotions
```

### Request Body

<ParamField body="promo_codes" type="string[]" required>
  Array of promotion codes to apply.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "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.

```bash theme={null}
DELETE /store/carts/{id}/promotions
```

### Request Body

<ParamField body="promo_codes" type="string[]" required>
  Array of promotion codes to remove.
</ParamField>

## Customer Association

### Update Customer

Associate the cart with a customer.

```bash theme={null}
POST /store/carts/{id}/customer
```

### Request Body

<ParamField body="customer_id" type="string">
  The customer ID to associate.
</ParamField>

<ParamField body="email" type="string">
  Customer email if not registered.
</ParamField>

**Source:** `packages/medusa/src/api/store/carts/[id]/customer/route.ts`

## Calculate Taxes

Manually trigger tax calculation for the cart.

```bash theme={null}
POST /store/carts/{id}/taxes
```

**Source:** `packages/medusa/src/api/store/carts/[id]/taxes/route.ts`

<Note>
  Taxes are usually calculated automatically when the shipping address is set or updated.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Checkout" icon="credit-card" href="/api/store/checkout">
    Complete the cart and create an order
  </Card>

  <Card title="Products" icon="box" href="/api/store/products">
    Browse products to add to cart
  </Card>
</CardGroup>