POST
/
v1
/
carts
/
:id
/
merge
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
}'

{
  "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"
    }
  ]
}
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.

​
Authentication

This endpoint requires a valid API key with carts:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
The target cart ID (cart to merge INTO)

​
Request Body

​
source_cart_id
string
required
The source cart ID (cart to merge FROM)
​
merge_strategy
string
default:"combine"
How to handle duplicate items: “combine” (add quantities), “keep_source”, “keep_target”
​
preserve_source_metadata
boolean
default:"true"
Whether to preserve metadata from source cart items
​
delete_source_cart
boolean
default:"true"
Whether to delete the source cart after merge

​
Response

Returns the merged cart object. 
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
}'

{
  "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"
    }
  ]
}