# Create/Update Cart

## Endpoint Details

<mark style="color:green;">`POST`</mark> `/cart/update`

### Headers

| Header        | Value                        |
| ------------- | ---------------------------- |
| Content-Type  | `application/json`           |
| Authorization | `Bearer <YOUR_ACCESS_TOKEN>` |

### Body

<table><thead><tr><th width="118.98040771484375">Parameter</th><th width="199.01190185546875">Type</th><th width="278">Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>Cart ID (leave empty to create a new cart)</td><td>false</td></tr><tr><td><code>items</code></td><td>array&#x3C;<a href="#cart-update-item">cartUpdateItem</a>></td><td>Array of items to add to the cart</td><td>true</td></tr><tr><td><code>loc</code></td><td><a href="/pages/IvoedyWb8YqfzF59Ppft#loc-object">locType</a></td><td>Location object for determining availability and shipping</td><td>true</td></tr><tr><td><code>promoCode</code></td><td>string</td><td>Promotional code to apply to the cart</td><td>false</td></tr><tr><td><code>isLegacy</code></td><td>boolean</td><td>Whether to return legacy identifiers</td><td>false</td></tr><tr><td><code>refresh</code></td><td>boolean</td><td>When <code>true</code>, a new access token will be generated</td><td>false</td></tr></tbody></table>

#### Cart Update Item

<table><thead><tr><th width="195">Parameter</th><th width="143">Type</th><th width="295">Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td><p></p><p>This parameter is <strong>REQUIRED</strong> when:</p><ul><li>Updating any personalized configurations for a specific item in the cart (e.g., engraving messages, or other personalization options)</li><li>Deleting a product that has personalizations</li></ul></td><td>false</td></tr><tr><td><code>partNumber</code></td><td>string</td><td>Unique identifier for the retailer's product variant</td><td>true</td></tr><tr><td><code>quantity</code></td><td>number</td><td>Quantity of the item</td><td>true</td></tr><tr><td><code>fulfillmentId</code></td><td>string</td><td>ID of the retailer's fulfillment method</td><td>true</td></tr><tr><td><code>engravingLines</code></td><td>array&#x3C;string></td><td>Array of engraving text lines (if applicable)</td><td>false</td></tr><tr><td><code>scheduledFor</code></td><td>string</td><td>ISO date string for scheduled delivery (onDemand only)</td><td>false</td></tr><tr><td><code>sku</code></td><td>string</td><td>Product SKU</td><td>false</td></tr></tbody></table>

### Response Details

<table><thead><tr><th width="156">Field</th><th width="159">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>statusCode</code></td><td>number</td><td>HTTP status code of the response</td></tr><tr><td><code>message</code></td><td>string</td><td>A brief message describing the result of the API call</td></tr><tr><td><code>metadata</code></td><td><a href="#metadata-object">metaDataObject</a></td><td>Contains metadata about the API call</td></tr><tr><td><code>auth</code></td><td><a href="/pages/4amDKkDBbASmenwDBAOp#auth-object">authObject</a></td><td>Authentication object, only when refresh in <code>true</code></td></tr><tr><td><code>cart</code></td><td><a href="/pages/1OwPN1FcCN3v9WXlVXEA#carttype">cartType</a></td><td>Cart details</td></tr></tbody></table>

#### Metadata Object

<table><thead><tr><th width="144">Field</th><th width="140">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>languages</code></td><td>Array&#x3C;string></td><td>List of supported languages for the response, e.g. ["en"]</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Unix timestamp (in milliseconds) when the response was generated</td></tr><tr><td><code>timezone</code></td><td>string</td><td>Timezone used for the response, always "UTC"</td></tr><tr><td><code>requestId</code></td><td>string</td><td>Unique identifier for the API request. Used for debugging and support</td></tr><tr><td><code>path</code></td><td>string</td><td>API path</td></tr><tr><td><code>version</code></td><td>string</td><td>API version used for the request</td></tr></tbody></table>

### Sample Request and Response

```bash
curl --location 'https://staging.api.liquidcommerce.cloud/cart/update' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "id": "",
    "items": [
        {
            "partNumber": "partnum_123abc456def",
            "quantity": 1,
            "fulfillmentId": "65830af0be8824843febdb8f"
        },
        {
            "partNumber": "partnum_124abc456def",
            "quantity": 1,
            "engravingLines": [
                "Happy birthday"
            ],
            "fulfillmentId": "65830af0be8824843febdb72"
        }
    ],
    "loc": {
        "address": {
            "one": "100 madison ave",
            "two": "apt 1707",
            "city": "New york",
            "state": "NY",
            "zip": "10016"
        }
    },
    "refresh": false
}'
```

{% tabs %}
{% tab title="200 " %}

```json
{
    "statusCode": 200,
    "message": "Create, build and manage carts.",
    "metadata": {
        "languages": [
            "en"
        ],
        "timestamp": 1731610845174,
        "timezone": "UTC",
        "requestId": "req_abc123xyz789",
        "path": "/api/cart/update",
        "version": "1.7.0"
    },
    "cart": {
        "id": "cart_abc123xyz789",
        "quantity": 1,
        "platformFee": 499,
        "deliveryFee": 0,
        "shippingFee": 1599,
        "engravingFee": 0,
        "discounts": 0,
        "giftCardTotal": 0,
        "subtotal": 5999,
        "total": 8097,
        "createdAt": "2024-11-14T19:00:45.433Z",
        "updatedAt": "2024-11-14T19:00:45.433Z",
        "items": [
            {
                "id": "item_abc123xyz789",
                "variantId": "var_abc123xyz789",
                "liquidId": "liq_abc123xyz789",
                "retailerId": "ret_abc123xyz789",
                "partNumber": "pn_abc123xyz789",
                "fulfillmentId": "ful_abc123xyz789",
                "upc": "88320002003",
                "catPath": "WINE > ROSE WINE",
                "volume": "1.5",
                "uom": "LITRE",
                "pack": false,
                "packDesc": "",
                "container": "Bottle",
                "containerType": "Bottle",
                "name": "Whispering Angel Rosé",
                "brand": "Chateau D'esclans",
                "scheduledFor": "",
                "abv": "14",
                "proof": "28",
                "size": "1.5 L",
                "price": 5999,
                "quantity": 1,
                "customerPlacement": "standard",
                "maxQuantity": 12,
                "unitPrice": 5999,
                "availableAt": "",
                "mainImage": "https://storage.example.com/images/products/image1.png",
                "images": [
                    "https://storage.example.com/images/products/image1.png",
                    "https://storage.example.com/images/products/image2.png",
                    "https://storage.example.com/images/products/image3.png",
                    "https://storage.example.com/images/products/image4.png",
                    "https://storage.example.com/images/products/image5.png"
                ],
                "attributes": {
                    "giftCard": {
                        "sender": "",
                        "message": "",
                        "recipients": [],
                        "sendDate": ""
                    },
                    "engraving": {
                        "isEngravable": true,
                        "hasEngraving": false,
                        "maxCharsPerLine": 0,
                        "maxLines": 0,
                        "fee": 0,
                        "location": "",
                        "lines": []
                    }
                }
            }
        ],
        "loc": {
            "coords": {
                "lat": 40.7447986,
                "long": -73.98530819999999
            },
            "address": {
                "one": "100 madison ave",
                "two": "apt 1707",
                "city": "New york",
                "state": "NY",
                "zip": "10016",
                "country": "US",
                "placesId": "place_abc123xyz789",
                "customerId": "cust_abc123xyz789",
                "type": "shipping",
                "lat": 40.7447986,
                "long": -73.98530819999999
            }
        },
        "retailers": [
            {
                "id": "ret_abc123xyz789",
                "name": "East Houston St Wine & Liquors",
                "platformFee": 499,
                "address": {
                    "one": "250 E Houston Street",
                    "two": "",
                    "city": "New York",
                    "state": "NY",
                    "zip": "10002",
                    "country": "US"
                },
                "fulfillments": [
                    {
                        "id": "ful_abc123xyz789",
                        "timezone": "America/New_York",
                        "type": "shipping",
                        "canEngrave": false,
                        "fees": {
                            "pack": {
                                "active": true,
                                "maxQuantity": 25,
                                "fee": 1599
                            },
                            "individual": {
                                "active": true,
                                "maxQuantity": 25,
                                "fee": 1599
                            },
                            "free": {
                                "active": false,
                                "min": 0
                            }
                        },
                        "expectation": {
                            "detail": "Ships in 2-3 days",
                            "short": "2-3 days"
                        },
                        "hours": {
                            "monday": {
                                "active": false,
                                "times": []
                            },
                            "tuesday": {
                                "active": false,
                                "times": []
                            },
                            "wednesday": {
                                "active": false,
                                "times": []
                            },
                            "thursday": {
                                "active": false,
                                "times": []
                            },
                            "friday": {
                                "active": false,
                                "times": []
                            },
                            "saturday": {
                                "active": false,
                                "times": []
                            },
                            "sunday": {
                                "active": false,
                                "times": []
                            }
                        },
                        "breaks": [],
                        "items": [
                            "item_abc123xyz789"
                        ],
                        "engravingFee": 0,
                        "shippingFee": 1599,
                        "deliveryFee": 0,
                        "subtotal": 5999
                    }
                ],
                "engravingFee": 0,
                "deliveryFee": 0,
                "shippingFee": 1599,
                "subtotal": 5999,
                "total": 8097
            }
        ],
        "attributes": {
            "promoCode": {
                "value": "",
                "freeDelivery": false,
                "freeServiceFee": false,
                "freeShipping": false
            },
            "amounts": {
                "fees": {
                    "shipping": 5999,
                    "onDemand": 0
                },
                "discounts": {
                    "shipping": 0,
                    "onDemand": 0,
                    "engraving": 0,
                    "service": 0,
                    "products": 0
                }
            }
        },
        "events": [
            {
                "type": "NoId",
                "message": "The cartId provided is empty, a new cart was created",
                "items": []
            },
            {
                "type": "PartnerProductConfigs",
                "message": "Item(s) have been removed, they're currently not available in your account's catalog. Check your LiquidCommerce Partner App account and add the product to you account, or just use our default catalog",
                "items": [
                    {
                        "partNumber": "pn_abc123xyz789",
                        "quantity": 1,
                        "fulfillmentId": "ful_abc123xyz789",
                        "id": "item_abc123xyz789"
                    }
                ]
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.liquidcommerce.cloud/services/cart-api/create-update-cart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.