> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add to Cart

> Add an item to the cart

# Add to Cart

Adds one or more items to the cart.

<Note>
  Add-to-cart is a **storefront** surface, not part of the OAuth `/api/v1` app
  API. It follows the Shopify-AJAX cart contract: requests are made against the
  storefront origin (your store domain), identity is the `cart` cookie token
  (not a Bearer access token), and the response is the **flat** Shopify cart
  object — not wrapped in a `{ status, type, data }` envelope. The endpoint
  accepts JSON, `multipart/form-data`, and `application/x-www-form-urlencoded`
  bodies.
</Note>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://your-store.launchmystore.io/cart/add.js" \
    -H "Content-Type: application/json" \
    -H "Cookie: cart=c1-xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx" \
    -d '{
      "items": [
        {
          "id": 639664,
          "quantity": 2
        }
      ]
    }'
  ```

  ```javascript Browser (fetch) theme={null}
  const response = await fetch('/cart/add.js', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      items: [
        { id: 639664, quantity: 2 }
      ]
    })
  });
  const cart = await response.json();
  ```
</CodeGroup>

## Body Parameters

<ParamField body="items" type="array" required>
  Array of items to add

  <Expandable title="Item Object">
    <ParamField body="id" type="string | integer" required>
      Variant ID to add
    </ParamField>

    <ParamField body="quantity" type="integer" default="1">
      Quantity to add
    </ParamField>

    <ParamField body="properties" type="object">
      Custom line item properties (e.g., personalization). Accepts a
      `{ "Key": "Value" }` object or an array of `{ name, value }` entries.
    </ParamField>

    <ParamField body="selling_plan" type="string">
      Selling plan ID for subscriptions
    </ParamField>
  </Expandable>
</ParamField>

## Shorthand Format

You can also use the shorthand format for adding a single item (no `items`
wrapper):

```json theme={null}
{
  "id": 639664,
  "quantity": 2
}
```

## Response

The response is the flat Shopify cart object (the same shape returned by
[Get Cart](/api-reference/cart/get)), reflecting the updated cart after the
add. For theme JavaScript, three extra top-level fields are included:

<ResponseField name="id" type="integer">
  Variant ID of the item that was added (used by cart-notification scripts)
</ResponseField>

<ResponseField name="key" type="string">
  Line item key of the added/merged line
</ResponseField>

<ResponseField name="items_changelog" type="object">
  `{ added: [{ id, quantity }], removed: [] }` describing the change
</ResponseField>

## Example Response

```json theme={null}
{
  "token": "c1-9a3f0c2e-7b1d-4e8a-9f2c-1a2b3c4d5e6f",
  "id": 639664,
  "key": "639664:default",
  "item_count": 2,
  "total_price": 5000,
  "currency": "USD",
  "items": [
    {
      "key": "639664:default",
      "id": 639664,
      "product_id": 12001,
      "variant_id": 639664,
      "title": "Classic T-Shirt",
      "variant_title": "Medium / Black",
      "quantity": 2,
      "price": 2500,
      "line_price": 5000,
      "sku": "TSHIRT-M-BLK",
      "image": {
        "src": "https://assets.launchmystore.io/images/tshirt-black.jpg",
        "alt": "Black T-Shirt"
      },
      "properties": {}
    }
  ],
  "items_changelog": {
    "added": [{ "id": 639664, "quantity": 2 }],
    "removed": []
  }
}
```

## Adding Items with Properties

Add personalized items with custom properties:

```json theme={null}
{
  "items": [
    {
      "id": 640900,
      "quantity": 1,
      "properties": {
        "Engraving": "Happy Birthday!",
        "Gift Wrap": "Yes"
      }
    }
  ]
}
```

## Errors

On failure (e.g. variant out of stock) the endpoint returns a Shopify-style
error body with the real HTTP status:

```json theme={null}
{
  "status": 422,
  "message": "Variant is out of stock",
  "description": "Variant is out of stock"
}
```

A non-AJAX browser form submission is redirected to `/cart` (HTTP 302)
instead of receiving a JSON body.