# 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="../../../types/checkout#customer">customer</a></td><td>Customer information </td><td>false</td></tr><tr><td><code>billingAddress</code></td><td><a href="../../../types/checkout#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="../../../types/checkout#giftoptions">giftOptions</a></td><td>Gift options if applicable</td><td>false</td></tr><tr><td><code>marketingPreferences</code></td><td><a href="../../../types/checkout#marketingpreferences">marketingPreferences</a></td><td>Marketing preferences</td><td>false</td></tr><tr><td><code>deliveryTips</code></td><td>array&#x3C;<a href="../../../types/checkout#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="../../../types/checkout#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="../../../authentication-api-integration/get-access-token#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="../../../types/checkout#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 %}