Update Cart Item

Update quantity or properties of an item in the cart

PUT /v1/carts/:id/items/:item_id

cURL

curl --location --request PUT 'https://api.stateset.com/v1/carts/cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/items/ci_abc123' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "quantity": 3,
    "notes": "Updated quantity"
}'

Response

{
  "id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "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": 3,
      "unit_price": 9999,
      "subtotal": 29997,
      "notes": "Updated quantity",
      "inventory_status": "in_stock",
      "available_quantity": 50
    },
    {
      "id": "ci_def456",
      "product_id": "prod_456",
      "product_name": "USB-C Cable",
      "quantity": 1,
      "unit_price": 1999,
      "subtotal": 1999
    },
    {
      "id": "ci_ghi789",
      "product_id": "prod_789",
      "variant_id": "var_red_medium",
      "product_name": "T-Shirt",
      "variant_name": "Red - Medium",
      "quantity": 1,
      "unit_price": 2499,
      "subtotal": 2499,
      "notes": "Gift wrap please"
    }
  ],
  "item_count": 5,
  "unique_item_count": 3,
  "subtotal": 34495,
  "updated_at": "2024-06-20T15:30:00Z",
  "last_activity": "2024-06-20T15:30:00Z",
  "messages": [
    {
      "type": "info",
      "message": "Item quantity updated"
    }
  ]
}

This endpoint updates an existing item in the cart. You can change quantity, add notes, or update metadata. Setting quantity to 0 removes the item.

Authentication

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

Authorization: Bearer YOUR_API_KEY

Path Parameters

id · string · required

The unique identifier of the cart

item_id · string · required

The unique identifier of the cart item

Request Body

quantity · integer

New quantity (set to 0 to remove item)

notes · string

Update special instructions

metadata · object

Update custom fields

validate_inventory · boolean · default: "true"

Validate inventory for quantity increase

Response

Returns the updated cart object.

cURL

curl --location --request PUT 'https://api.stateset.com/v1/carts/cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/items/ci_abc123' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "quantity": 3,
    "notes": "Updated quantity"
}'

Response

{
  "id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "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": 3,
      "unit_price": 9999,
      "subtotal": 29997,
      "notes": "Updated quantity",
      "inventory_status": "in_stock",
      "available_quantity": 50
    },
    {
      "id": "ci_def456",
      "product_id": "prod_456",
      "product_name": "USB-C Cable",
      "quantity": 1,
      "unit_price": 1999,
      "subtotal": 1999
    },
    {
      "id": "ci_ghi789",
      "product_id": "prod_789",
      "variant_id": "var_red_medium",
      "product_name": "T-Shirt",
      "variant_name": "Red - Medium",
      "quantity": 1,
      "unit_price": 2499,
      "subtotal": 2499,
      "notes": "Gift wrap please"
    }
  ],
  "item_count": 5,
  "unique_item_count": 3,
  "subtotal": 34495,
  "updated_at": "2024-06-20T15:30:00Z",
  "last_activity": "2024-06-20T15:30:00Z",
  "messages": [
    {
      "type": "info",
      "message": "Item quantity updated"
    }
  ]
}