# Prepare

## Endpoint Details

<mark style="color:green;">`POST`</mark> `/checkout/prepare`

### Headers

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

### Body

<table><thead><tr><th width="238.114501953125">Parameter</th><th width="188.82733154296875">Type</th><th width="241.157958984375">Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>cartId</code></td><td>string</td><td>ID of the cart to checkout<br><strong>(required if you dont pass <code>token</code>)</strong></td><td>false</td></tr><tr><td><code>token</code></td><td>string</td><td>ID of the checkout <strong>(required if you dont pass <code>cartId</code>)</strong></td><td>false</td></tr><tr><td><code>customer</code></td><td><a href="/pages/eUQZtAGxjNOgKAoqjISX#customer">customer</a></td><td>Customer information </td><td>false</td></tr><tr><td><code>billingAddress</code></td><td><a href="/pages/eUQZtAGxjNOgKAoqjISX#checkout-billingaddress">billingAddress</a></td><td>Billing address details</td><td>false</td></tr><tr><td><code>hasSubstitutionPolicy</code></td><td>boolean</td><td>Whether substitution policy is accepted</td><td>false</td></tr><tr><td><code>isGift</code></td><td>boolean</td><td>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</td><td>false</td></tr><tr><td><code>hasAgeVerify</code></td><td>boolean</td><td>Should the checkout verify age</td><td>false</td></tr><tr><td><code>billingSameAsShipping</code></td><td>boolean</td><td>Whether billing address is same as shipping</td><td>false</td></tr><tr><td><code>giftOptions</code></td><td><a href="/pages/eUQZtAGxjNOgKAoqjISX#giftoptions">giftOptions</a></td><td>Gift options if applicable</td><td>false</td></tr><tr><td><code>marketingPreferences</code></td><td><a href="/pages/eUQZtAGxjNOgKAoqjISX#marketingpreferences">marketingPreferences</a></td><td>Marketing preferences</td><td>false</td></tr><tr><td><code>deliveryTips</code></td><td>array&#x3C;<a href="/pages/eUQZtAGxjNOgKAoqjISX#deliverytip">deliveryTip</a>></td><td>Array of delivery tip objects</td><td>false</td></tr><tr><td><code>deliveryInstructions</code></td><td>array&#x3C;<a href="/pages/eUQZtAGxjNOgKAoqjISX#deliveryinstruction">deliveryInstruction</a>></td><td>Delivery instructions for on-demand orders only</td><td>false</td></tr><tr><td><code>shippingAddressTwo</code></td><td>string</td><td>Optional second line for the shipping address</td><td>false</td></tr><tr><td><code>acceptedAccountCreation</code></td><td>boolean</td><td>Whether customer accepted account creation</td><td>false</td></tr><tr><td><code>scheduledDelivery</code></td><td>string</td><td>Scheduled delivery datetime (ISO format)</td><td>false</td></tr><tr><td><code>payment</code></td><td>string</td><td>Payment method identifier</td><td>false</td></tr><tr><td><code>promoCode</code></td><td>string</td><td>Promotional code to apply a discount to the checkout</td><td>false</td></tr><tr><td><code>giftCards</code></td><td>array&#x3C;string></td><td>Array of gift card codes to apply as payment methods</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 set to <code>true</code>, a new access token will be generated and returned</td><td>false</td></tr></tbody></table>

{% hint style="warning" %}
**Required:** You must provide either `cartId` or `token` (or both). Requests without at least one of these parameters will fail.
{% endhint %}

### Response Details

<table><thead><tr><th width="226">Field</th><th width="184">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>statusCode</code></td><td>number</td><td>Internal 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>checkout</code></td><td><a href="/pages/eUQZtAGxjNOgKAoqjISX#checkouttype">checkoutType</a></td><td>Checkout type</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/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": "john.d.joe@gmail.com",
        "phone": "9732119920",
        "birthDate": "11-22-1998",
        "hasAgeVerify": true
    },
    "billingAddress": {
        "firstName": "NewJoe",
        "lastName": "NewJohn",
        "email": "joe.new.john@gmail.com",
        "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
}'
```

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

```json
{
    "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": "user@example.com",
            "firstName": "John",
            "company": "",
            "lastName": "Doe",
            "phone": "(555) 555-5555",
            "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": "user@example.com",
            "country": "US",
            "firstName": "John",
            "lastName": "Doe",
            "company": "",
            "phone": "(555) 555-5555"
        },
        "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": ""
    }
}
```

{% 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/checkout-api/prepare.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.