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

# Merge Carts

> Merge a guest cart with a customer cart after login

<Note>
  This endpoint merges items from one cart (typically a guest cart) into another cart (typically the logged-in customer's cart). Useful when customers add items before logging in.
</Note>

## Authentication

This endpoint requires a valid API key with `carts:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  The target cart ID (cart to merge INTO)
</ParamField>

## Request Body

<ParamField body="source_cart_id" type="string" required>
  The source cart ID (cart to merge FROM)
</ParamField>

<ParamField body="merge_strategy" type="string" default="combine">
  How to handle duplicate items: "combine" (add quantities), "keep\_source", "keep\_target"
</ParamField>

<ParamField body="preserve_source_metadata" type="boolean" default="true">
  Whether to preserve metadata from source cart items
</ParamField>

<ParamField body="delete_source_cart" type="boolean" default="true">
  Whether to delete the source cart after merge
</ParamField>

### Response

Returns the merged cart object.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/carts/cart_customer_123/merge' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "source_cart_id": "cart_guest_456",
      "merge_strategy": "combine",
      "delete_source_cart": true
  }'
  ```

  ```javascript Node.js theme={null}
  const mergedCart = await stateset.carts.merge(
    'cart_customer_123',
    {
      source_cart_id: "cart_guest_456",
      merge_strategy: "combine",
      delete_source_cart: true
    }
  );
  ```

  ```python Python theme={null}
  merged_cart = stateset.carts.merge(
    'cart_customer_123',
    source_cart_id="cart_guest_456",
    merge_strategy="combine",
    delete_source_cart=True
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "cart_customer_123",
    "object": "cart",
    "customer_id": "cust_abc123",
    "status": "active",
    "items": [
      {
        "id": "ci_abc123",
        "product_id": "prod_123",
        "variant_id": "var_blue_large",
        "product_name": "Wireless Headphones",
        "variant_name": "Blue - Large",
        "quantity": 5,
        "unit_price": 9999,
        "subtotal": 49995,
        "source": "merged",
        "metadata": {
          "original_cart": "cart_customer_123",
          "merged_quantity": 2,
          "merge_timestamp": "2024-06-20T18:00:00Z"
        }
      },
      {
        "id": "ci_new789",
        "product_id": "prod_456",
        "product_name": "USB-C Cable",
        "quantity": 2,
        "unit_price": 1999,
        "subtotal": 3998,
        "source": "merged",
        "metadata": {
          "original_cart": "cart_guest_456",
          "merge_timestamp": "2024-06-20T18:00:00Z"
        }
      }
    ],
    "item_count": 7,
    "unique_item_count": 2,
    "subtotal": 53993,
    "total": 58792,
    "merge_details": {
      "source_cart_id": "cart_guest_456",
      "items_merged": 2,
      "items_combined": 1,
      "merge_timestamp": "2024-06-20T18:00:00Z",
      "source_cart_deleted": true
    },
    "updated_at": "2024-06-20T18:00:00Z",
    "messages": [
      {
        "type": "success",
        "message": "Successfully merged 2 items from guest cart"
      }
    ]
  }
  ```
</ResponseExample>