Prepare

Prepares a checkout session based on the provided cart and user information

Endpoint Details

POST /checkout/prepare

Headers

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

Body

Parameter	Type	Description	Required
cartId	string	ID of the cart to checkout
customer	customer	Customer information
billingAddress	billingAddress	Billing address details
hasSubstitutionPolicy	boolean	Whether substitution policy is accepted
isGift	boolean	When the order is set as gift (isGift is set to true), the system adds gift messaging, special packaging, and gift receipts with optional sender anonymity
hasAgeVerify	boolean	Should the checkout verify age
billingSameAsShipping	boolean	Whether billing address is same as shipping
giftOptions	giftOptions	Gift options if applicable
marketingPreferences	marketingPreferences	Marketing preferences
deliveryTips	array<deliveryTip>	Array of delivery tip objects
deliveryInstructions	array<deliveryInstruction>	Delivery instructions for on-demand orders only
shippingAddressTwo	string	Optional second line for the shipping address
acceptedAccountCreation	boolean	Whether customer accepted account creation
scheduledDelivery	string	Scheduled delivery datetime (ISO format)
payment	string	Payment method identifier
promoCode	string	Promotional code to apply a discount to the checkout
giftCards	array<string>	Array of gift card codes to apply as payment methods
isLegacy	boolean	Whether to return legacy identifiers
refresh	boolean	When set to true, a new access token will be generated and returned

Response Details

Field	Type	Description
statusCode	number	Internal 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
checkout	checkoutType	Checkout type

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/checkout/prepare' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "cartId": "cart_abc123xyz789", // create a new cart
    "customer": {
        "firstName": "Joe",
        "lastName": "John",
        "email": "[email protected]",
        "phone": "9732119920",
        "birthDate": "11-22-1998",
        "hasAgeVerify": true
    },
    "billingAddress": {
        "firstName": "NewJoe",
        "lastName": "NewJohn",
        "email": "[email protected]",
        "phone": "1234324987",
        "one": "22 Washington Ave",
        "two": "",
        "city": "Cliffside Park",
        "state": "NJ",
        "zip": "07010"
    },
    "hasSubstitutionPolicy": true,
    "isGift": false,
    "billingSameAsShipping": true,
    "giftOptions": {
        "message": "",
        "recipient": {
            "name": "",
            "phone": "",
            "email": ""
        }
    },
    "marketingPreferences": {
        "canEmail": true,
        "canSms": true
    },
    "deliveryTips": [
        {
            "fulfillmentId": "6570c3ec700628ce1910c105",
            "tip": 2500
        }
    ],
    "refresh": true
}'

200

{
    "statusCode": 200,
    "message": "Prepare a checkout prior to processing.",
    "metadata": {
        "languages": [
            "en"
        ],
        "timestamp": 1731613340101,
        "timezone": "UTC",
        "requestId": "req_abc123xyz789",
        "path": "/api/checkout/prepare",
        "version": "1.7.0"
    },
    "auth": {
        "token": "auth_token_abc123xyz789",
        "type": "ACCESS_TOKEN",
        "exp": 1731679155851
    },
    "checkout": {
        "token": "checkout_token_abc123xyz789",
        "cartId": "cart_abc123xyz789",
        "customer": {
            "id": "usr_abc123xyz789",
            "email": "[email protected]",
            "firstName": "John",
            "company": "",
            "lastName": "Doe",
            "phone": "[phone]",
            "profileImage": "",
            "birthDate": "1998-11-22T00:00:00.000Z",
            "createdAt": "2024-11-14T19:13:34.231Z",
            "updatedAt": "2024-11-14T19:42:20.314Z"
        },
        "createdAt": "2024-11-14T19:13:35.004Z",
        "updatedAt": "2024-11-14T19:42:20.420Z",
        "hasAgeVerify": false,
        "hasSubstitutionPolicy": true,
        "acceptedAccountCreation": false,
        "isGift": false,
        "billingSameAsShipping": true,
        "giftOptions": {
            "message": "",
            "recipient": {
                "name": "",
                "email": "",
                "phone": ""
            }
        },
        "marketingPreferences": {
            "canEmail": true,
            "canSms": true
        },
        "shippingAddress": {
            "one": "100 madison ave",
            "two": "",
            "city": "New york",
            "state": "NY",
            "zip": "10016",
            "country": "US"
        },
        "billingAddress": {
            "one": "100 madison ave",
            "two": "",
            "city": "New york",
            "state": "NY",
            "zip": "10016",
            "email": "[email protected]",
            "country": "US",
            "firstName": "John",
            "lastName": "Doe",
            "company": "",
            "phone": "[phone]"
        },
        "amounts": {
            "subtotal": 5999,
            "engraving": 0,
            "service": 0,
            "shipping": 1599,
            "delivery": 0,
            "platform": 499,
            "discounts": 0,
            "giftCards": 0,
            "tax": 684,
            "tip": 0,
            "total": 8781,
            "details": {
                "discounts": {
                    "products": 0,
                    "delivery": 0,
                    "shipping": 0,
                    "engraving": 0,
                    "service": 0
                },
                "taxes": {
                    "bag": 5,
                    "bottleDeposits": 5,
                    "retailDelivery": 0,
                    "products": 532,
                    "delivery": 0,
                    "shipping": 142
                }
            }
        },
        "items": [
            {
                "variantId": "var_abc123xyz789",
                "liquidId": "liq_abc123xyz789",
                "cartItemId": "item_abc123xyz789",
                "retailerId": "ret_abc123xyz789",
                "fulfillmentId": "ful_abc123xyz789",
                "name": "Whispering Angel Rosé",
                "brand": "Chateau D'esclans",
                "mainImage": "https://storage.example.com/images/products/image1.png",
                "image": "https://storage.example.com/images/products/image1.png",
                "size": "1.5 L",
                "pack": false,
                "packDesc": "",
                "volume": "1.5",
                "uom": "LITRE",
                "abv": "14",
                "containerType": "Bottle",
                "container": "Bottle",
                "partNumber": "88320002003_ret_abc123xyz789",
                "upc": "88320002003",
                "catPath": "WINE > ROSE WINE",
                "customerPlacement": "standard",
                "price": 5999,
                "unitPrice": 5999,
                "quantity": 1,
                "attributes": {
                    "giftCard": {
                        "sender": "",
                        "message": "",
                        "recipients": [],
                        "sendDate": ""
                    },
                    "engraving": {
                        "isEngravable": true,
                        "hasEngraving": false,
                        "maxCharsPerLine": 0,
                        "maxLines": 0,
                        "fee": 0,
                        "location": "",
                        "lines": []
                    }
                },
                "bottleDeposits": 5,
                "tax": 532
            }
        ],
        "retailers": [
            {
                "id": "ret_abc123xyz789",
                "name": "East Houston St Wine & Liquors",
                "address": {
                    "one": "250 E Houston Street",
                    "two": "",
                    "city": "New York",
                    "state": "NY",
                    "zip": "10002",
                    "country": "US"
                },
                "subtotal": 5999,
                "engraving": 0,
                "service": 0,
                "shipping": 1599,
                "delivery": 0,
                "platform": 499,
                "discounts": 0,
                "giftCards": 0,
                "tax": 684,
                "tip": 0,
                "total": 8781,
                "details": {
                    "discounts": {
                        "products": 0,
                        "delivery": 0,
                        "shipping": 0,
                        "engraving": 0,
                        "service": 0
                    },
                    "taxes": {
                        "bag": 5,
                        "bottleDeposits": 5,
                        "retailDelivery": 0,
                        "products": 532,
                        "delivery": 0,
                        "shipping": 142
                    }
                },
                "fulfillments": [
                    {
                        "id": "ful_abc123xyz789",
                        "scheduledFor": "",
                        "type": "shipping",
                        "expectation": {
                            "detail": "Ships in 2-3 days",
                            "short": "2-3 days"
                        },
                        "subtotal": 5999,
                        "engraving": 0,
                        "service": 0,
                        "shipping": 1599,
                        "delivery": 0,
                        "discounts": 0,
                        "giftCards": 0,
                        "tip": 0,
                        "items": [
                            "item_abc123xyz789"
                        ],
                        "total": 8282,
                        "details": {
                            "discounts": {
                                "products": 0,
                                "delivery": 0,
                                "shipping": 0,
                                "engraving": 0,
                                "service": 0
                            },
                            "taxes": {
                                "bag": 5,
                                "bottleDeposits": 5,
                                "retailDelivery": 0,
                                "products": 532,
                                "delivery": 0,
                                "shipping": 142
                            }
                        },
                        "tax": 684
                    }
                ]
            }
        ],
        "payment": ""
    }
}