Cart

A full reference to a cart type for different Liquid Commerce APIs.

CartType

Attribute	Description
id: string	unique cart identifier
quantity: number	total number of items in cart
platformFee: number	platform fee for the cart
deliveryFee: number	total delivery fees
engravingFee: number	total engraving fees
shippingFee: number	total shipping fees
discounts: number	total discount fees
giftCardTotal: number	total value of applied gift cards
subtotal: number	cart subtotal before fees/discounts
total: number	final cart total
isPresaleLocked: boolean	indicates if the cart is locked to a single presale item
presaleExpiresAt: Date | null	the timestamp when the presale lock expires
createdAt: Date	cart creation timestamp
updatedAt: Date	last update timestamp
items: Array<CartItem>	array of cart items
loc: LocType	location information
retailers: Array<CartRetailer>	array of retailers for items
attributes: CartAttributes	cart-level attributes
events: Array<CartEvent>	cart-related events, Cart Events

CartItem

Attribute	Description
id: string	identifier of the item
retailerId: string	identifier of retailer providing item
fulfillmentId: string	identifier of fulfillment method
variantId: string	product variant identifier
liquidId: string	internal LiquidCommerce product identifier
salsifyGrouping: string [optional]	optional Salsify grouping identifier
salsifyPid: string [optional]	optional Salsify product identifier
partNumber: string	retailer's part number
upc: string	universal product code
name: string	product name
brand: string	product brand
size: string	product size
volume: string	product volume
uom: string	unit of measure
catPath: string	category path
abv: string	alcohol by volume, ex: 40 (40%)
proof: string	alcohol proof
container: string	product container, ex: Bottle
containerType: string	product container type, ex: Glass
customerPlacement: CustomerPlacement	Indicates fulfillment type
pack: boolean	whether the product is a pack, ex: true
packDesc: string	if the product is a pack and a description is available, ex: 8pk
quantity: number	quantity of item
maxQuantity: number	maximum allowed quantity
unitPrice: number	price per unit
price: number	total price for quantity
scheduleFor: string | Date	scheduled delivery date/time
availableAt: string | Date	availability date/time
images: Array<string>	Product images
mainImage: string	primary product image
attributes: CartItemAttributes	item-specific attributes

CustomerPlacement

Attribute	Description
standard: string	Item in stock and ready to ship
back_order: string	Item out of stock, fulfillment upon restock
pre_sale: string	Item can be purchased now, ships on release date

CartRetailer

Attribute	Description
id: string	retailer identifier
name: string	retailers name, ex: Liquid Wine and Spirits
platformFee: number	platform fee for retailer
deliveryFee: number	retailer's delivery fee
shippingFee: number	retailer's shipping fee
engravingFee: number	retailer's engraving fee
subtotal: number	Current subtotal for retailer items
total: number	Total amount including all fees and taxes
address: RetailerAddress	location information split out to individual values for the street, city, state, zip code and country
fulfillments: Array<RetailerFulfillment>	retailer available fulfillment configurations

CartAttributes

Attribute	Description
promoCode: CartAttributesPromoCode	applied promotional code
amounts: CartAttributesAmounts	cart amount calculations

CartEvent

Attribute	Description
type: CartEventTypes	type of cart event
message: string	event description
items: Array<Partial<CartItem>>	affected items if applicable

CartEventTypes

ENUM VALUES
OutOfStock
PresaleNotStarted
PresaleExpired
PresaleMixedCart
ItemsRequestedNotAdded
ItemEngravingError
RemovedExistingCartItems
RetailerMinNotMet
NoItemsInCart
InvalidId
NoId
CartCheckoutProcessed
NewCart
ItemIdNotFound
ItemsRemoved
RetailerFulfillmentInvalid
CouponProcessingError
CouponNotFound
CouponExpired
NoApplicableDiscount
CouponNotStarted
MinimumOrderValueNotMet
MinimumOrderUnitsNotMet
QuotaExceeded
UserLimitExceeded
NotFirstPurchase
InvalidCoupon
InvalidDomain
InvalidRequirements
InvalidOrganization
PresaleItemsNotAllowed
ProductNotEligible
NotEnoughPreviousOrders

CartAttributesPromoCode

Attribute	Description
value: string	the promotional code value
freeDelivery: boolean	whether promo provides free delivery
freeServiceFee: boolean	whether promo waives service fees
freeShipping: boolean	whether promo provides free shipping

CartAttributesAmounts

Attribute	Description
fees: CartAttributesAmountsFees	fee calculations
discounts: CartAttributesAmountsDiscounts	Discount calculations

CartAttributesAmountsFees

Attribute	Description
shipping: number	total shipping fees
onDemand: number	total on-demand delivery fees

CartAttributesAmountsDiscounts

Attribute	Description
shipping: number	shipping discounts
onDemand: number	on-demand delivery discounts
engraving: number	engraving discounts
service: number	service fee discounts
products: number	product discounts

CartItemAttributes

Attribute	Description
engraving: CartItemEngraving	Engraving options/configuration
giftCard: CartItemGiftCart	Gift card options
presale: ProductPresale	Representing a product presale

CartItemEngraving

Attribute	Description
isEngravable: boolean	whether item can be engraved
hasEngraving: boolean	whether engraving is applied
fee: boolean	engraving service fee
maxCharsPerLine: number	maximum characters per line
maxLines: number	maximum number of lines
location: string	engraving placement
lines: Array<string>	engraving text content

CartItemGiftCart

Attribute	Description
sender: string	the sender of the gift
message: string	the message attached to the gift
recipients: Array<string>	the list of recipients of the gift
sendDate: string	the date when the gift should be sent

Sample cart

Cart Object

{
        "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
            },
            "giftCards": [],
            "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"
                    }
                ]
            }
        ]
    }