Create/Update Cart

Creates a new cart or updates an existing cart with items

Endpoint Details

POST /cart/update

Headers

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

Body

Parameter	Type	Description	Required
id	string	Cart ID (leave empty to create a new cart)
items	array<cartUpdateItem>	Array of items to add to the cart
loc	locType	Location object for determining availability and shipping
promoCode	string	Promotional code to apply to the cart
isLegacy	boolean	Whether to return legacy identifiers
refresh	boolean	When true, a new access token will be generated

Cart Update Item

Parameter	Type	Description	Required
id	string	This parameter is REQUIRED when: Updating any personalized configurations for a specific item in the cart (e.g., engraving messages, or other personalization options) Deleting a product that has personalizations
partNumber	string	Unique identifier for the retailer's product variant
quantity	number	Quantity of the item
fulfillmentId	string	ID of the retailer's fulfillment method
engravingLines	array<string>	Array of engraving text lines (if applicable)
scheduledFor	string	ISO date string for scheduled delivery (onDemand only)
sku	string	Product SKU

Response Details

Field	Type	Description
statusCode	number	HTTP status code of the response
message	string	A brief message describing the result of the API call
metadata	metaDataObject	Contains metadata about the API call
auth	authObject	Authentication object, only when refresh in true
cart	cartType	Cart details

Metadata Object

Field	Type	Description
languages	Array<string>	List of supported languages for the response, e.g. ["en"]
timestamp	string	Unix timestamp (in milliseconds) when the response was generated
timezone	string	Timezone used for the response, always "UTC"
requestId	string	Unique identifier for the API request. Used for debugging and support
path	string	API path
version	string	API version used for the request

Sample Request and Response

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
}'

200

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