# Create a Cart
## Create a Cart
`POST` `https://graph.whisk.com/v1/carts`
You can provide both `recipeIds`or items alongside a `retailerId`for Whisk to generate a Cart.
#### Request Body
| Name | Type | Description |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| language | string | The language to use for the cart |
| retailerId | string | Retailer Id or name to generate a Cart for. available retailers Example: `tesco, 9b032cd7ca5d11e7ae7e42010a9a0035` |
| recipeIds | array | An array of strings representing ids of recipes. The cart will be generated based on recipe ingredients. The id can be represented by GraphID or recipe URL |
| items | array | An array of Shopping Cart Items to use for generating a Cart. It can be raw text or specific store item |
| labels | object | The flag which controls where Whisk should create a state for Cart on its side to manage later. Labels can be used later for filtering carts. Default: `false` |
| combineItems | boolean | Controls combining submitted items into single CartItem. `1 tbsp olive oil` and `30ml olive oil` can be combined with the single offered products from the retailer. Default: `true` |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"id": "b35ababeefa0452ebd9bac430417254d",
"retailer": {
"id": "898003be304e49b084ac6224adc7ff53",
"name": "Tesco",
"displayName": "Tesco",
"country": "GB",
"currency": "GBP",
"logo": {
"url": "https://res.cloudinary.com/whisk/image/upload/whisk3/supermarket_select_dropdown/tesco-logo.png",
"width": 134,
"height": 36
},
"urls": {
"signupUrl": "https://secure.tesco.com/account/en-GB/register",
"forgotPasswordUrl": "https://secure.tesco.com/account/en-GB/forgotten-password",
"trolleyUrl": "https://www.tesco.com/groceries/en-GB/slots"
}
},
"items": [
{
"id": "28c47e7684704e73bce11b74300dc6b7",
"sourceList": [
{
"name": "1 egg",
"groupId": "f4e354c79e984fe6bad72a9f8e0e0de9"
},
{
"name": "4 large eggs"
},
{
"name": "4 eggs",
"groupId": "a0316893c5404d689fe91f9f2adbebc3"
}
],
"product": {
"sku": "299626009",
"name": "Tesco 15 Eggs",
"quantity": {
"count": 1
},
"price": {
"list": 1.19
},
"images": [
{
"url": "https://img.tesco.com/Groceries/pi/043/5057545736043/IDShot_540x540.jpg"
}
],
"url": "https://www.tesco.com/groceries/en-GB/products/299626009"
},
"combined": {
"name": "9 egg"
},
"analysis": {
"canonicalName": "EGG",
"category": {
"id": "38f0d9f7-d19d-407d-bfc3-17258c57d954",
"name": "DAIRY AND EGGS"
}
}
},
...
{
"id": "0a33e8d087ce4de4a188e2f504a087ea",
"sourceList": [
{
"name": "2 tsp rapeseed oil",
"groupId": "a0316893c5404d689fe91f9f2adbebc3"
}
],
"product": {
"sku": "281921684",
"name": "Tesco Organic Rapeseed Oil 500Ml",
"quantity": {
"count": 1
},
"price": {
"list": 1.5
},
"images": [
{
"url": "https://img.tesco.com/Groceries/pi/749/0000003243749/IDShot_540x540.jpg"
}
],
"url": "https://www.tesco.com/groceries/en-GB/products/281921684"
}
}
],
"groups": [
{
"id": "a0316893c5404d689fe91f9f2adbebc3",
"type": "Recipe",
"displayName": "Omelette pancakes with tomato & pepper sauce",
"recipe": {
"id": "9773cb7eca5d11e7ae7e42010a9a0035",
"name": "Omelette pancakes with tomato & pepper sauce",
"description": "Healthy, low-calorie and gluten-free - these herby egg 'pancakes' will become your go-to favourite for a quick midweek meal",
"ingredients": [
{
"text": "4 large eggs"
},
{
"text": "handful basil leaves"
},
{
"text": "2 tsp rapeseed oil, plus a little extra for the pancakes"
},
{
"text": "1 yellow pepper, quartered, deseeded and thinly sliced"
},
{
"text": "2 garlic cloves, thinly sliced"
},
{
"text": "1 tbsp cider vinegar"
},
{
"text": "400g can chopped tomatoes"
},
{
"text": "wholemeal bread or salad leaves, to serve"
}
],
"images": [
{
"url": "https://www.bbcgoodfood.com/sites/default/files/styles/recipe/public/recipe_images/omelette-pancakes-with-tomato-pepper-sauce.jpg",
"responsive": {
"url": "https://whisk-res.cloudinary.com/image/upload/v1523012138/recipe/758058656142eaae402f1781e18c527c.jpg",
"width": 500,
"height": 454
}
}
],
"videos": [],
"source": {
"name": "bbcgoodfood.com",
"displayName": "BBC Good Food",
"sourceRecipeUrl": "https://www.bbcgoodfood.com/recipes/omelette-pancakes-tomato-pepper-sauce",
"license": "Fairuse",
"image": {
"url": "http://whisk-res.cloudinary.com/image/upload/v1527610208/publishers/logos/bbcgoodfood-logo.png",
"responsive": {
"url": "http://whisk-res.cloudinary.com/image/upload/v1527610208/publishers/logos/bbcgoodfood-logo.png",
"width": 256,
"height": 256
}
}
},
"numberOfServings": 2
}
},
...
],
"created": 1532503799,
"expiresIn": 1533108599,
"labels": {
"myId": "some value"
}
}
```
{% endtab %}
{% endtabs %}
### Sample Request
```bash
curl -X POST "https://graph.whisk.com/v1/carts" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Token " \
-d '{
"retailerId": "tesco",
"items": [
{
"raw": {
"name": "4 large eggs"
}
}
],
"recipeIds": [
"9773cb7eca5d11e7ae7e42010a9a0035",
"https://www.mccormick.com/recipes/breakfast-brunch/quick-and-easy-french-toast"
],
"labels": {
"myId": "some value"
}
}'
```
### Combined Items
Whisk supports intelligent algorithm for combining similar items into one, to improve shopping list experience.
Items like `2 eggs` and `28g of eggs yolk`can be combined into one item `4 eggs`.
Automatic combination of items is enabled by default, you can pass `combineItems = false` to disable it.
### Supported Retailers
Not every retailer provides us with information about inventory, so for some retailers we can't match store items and create a cart. You still can check out items for these retailers, check [landing url checkout section](/master/api/retailers/retailers-checkout-flow.md#via-landing-url).
You can find if we support matching for a retailer and able to create a cart [here in the retailer’s list ](/master/resources/supported-retailers.md)in `Store Inventory` column.
## Body Parameters
### ShoppingCartItem
| ATTRIBUTE | TYPE | DESCRIPTION |
| --------- | ------------------------------------------------------------------- | ----------- |
| storeItem | [StoreItemValue](/master/api/carts/create-a-cart.md#storeitemvalue) | |
| raw | [RawItemValue](/master/api/carts/create-a-cart.md#rawitemvalue) | |
### StoreItemValue
| ATTRIBUTE | TYPE | DESCRIPTION |
| --------- | ------------------------------------------------------------------- | -------------------------------------------- |
| sku\* | string | item identifier in Retailer |
| quantity | integer | number of items to checkout Default value: 1 |
| source | [CartItemSource](/master/api/carts/create-a-cart.md#cartitemsource) | source for store product |
### RawItemValue
| ATTRIBUTE | TYPE | DESCRIPTION |
| --------- | ------ | ------------------------------------ |
| name\* | string | raw item text. Example: 1 tbsp sugar |
### CartItemSource
| ATTRIBUTE | TYPE | DESCRIPTION |
| --------- | ------ | ---------------- |
| name\* | string | source item text |
| groupId | string | group identifier |
## Response
| ATTRIBUTE | TYPE | DESCRIPTION |
| ---------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| id\* | string | unique cart identifier |
| retailer\* | [Retailer](/master/api/carts/create-a-cart.md#retailer) | store details |
| items\* | array \[[CartItemResponse](/master/api/carts/create-a-cart.md#cartitemresponse)] | matched products |
| groups\* | array \[[CartGroupResponse](/master/api/carts/create-a-cart.md#cartgroupresponse)] | ingredients can be grouped by recipe or another arbitrary group |
| created\* | long | time of cart creation; in Unix timestamp format (seconds) |
| expiresIn | long | The time when cart will be expired; in Unix timestamp format (seconds) |
### Retailer
| ATTRIBUTE | TYPE | DESCRIPTION |
| ----------- | ---------------------------------------------------------------- | ----------- |
| id\* | string | |
| name\* | string | |
| displayName | string | |
| country | string | |
| currency | string | |
| logo | ImageContainer | |
| urls | [RetailerUrls](/master/api/carts/create-a-cart.md#retailer-urls) | |
### CartItemResponse
| ATTRIBUTE | TYPE | DESCRIPTION |
| ------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| id\* | string | unique cart item identifier |
| sourceList\* | array \[[CartItemSource](/master/api/carts/create-a-cart.md#cartitemsource)] | list of original ingredients related to the current item |
| product | [CartProductOption](/master/api/carts/create-a-cart.md#cartproductoption) | store item |
| combined | array \[[CombinedProductsInfo](/master/api/carts/create-a-cart.md#combinedproductsinfo)] | information about combined items, if items were combined by a similar product |
| analysis | object | Analysis for cart item (category, product canonical name) |
### Retailer Urls
| ATTRIBUTE | TYPE | DESCRIPTION |
| ------------------- | ------ | ----------- |
| signupUrl\* | string | |
| forgotPasswordUrl\* | string | |
| trolleyUrl\* | string | |
### CartProductOption
| ATTRIBUTE | TYPE | DESCRIPTION |
| ---------- | ----------------------------------------------------------------------------- | ------------------------------------- |
| sku\* | string | store item identifier |
| name\* | string | store item name |
| quantity\* | [CartProductQuantity](/master/api/carts/create-a-cart.md#cartproductquantity) | quantity of product items |
| price | [CartItemPrice](/master/api/carts/create-a-cart.md#cartitemprice) | price for the number of products |
| images\* | array \[ImageContainer] | |
| url | string | link to the product page in the store |
### CartGroupResponse
| ATTRIBUTE | TYPE | DESCRIPTION |
| ------------- | ------------- | ------------------------------------------------------------------------------------- |
| id\* | string | A unique cart group identifier |
| type\* | enum | ingredients can be grouped by recipe or custom group Possible values: Recipe, Custom. |
| displayName\* | string | group display name |
| recipe | RecipeDetails | recipe details |
### CartItemPrice
| ATTRIBUTE | TYPE | DESCRIPTION |
| --------- | ------ | ----------- |
| list\* | double | list price |
### CartProductQuantity
| ATTRIBUTE | TYPE | DESCRIPTION |
| --------- | ------- | --------------- |
| count\* | integer | number of items |
### CombinedProductsInfo
| ATTRIBUTE | TYPE | DESCRIPTION |
| --------- | ------ | ---------------------- |
| name\* | string | name of combined items |
---
# 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.whisk.com/master/api/carts/create-a-cart.md?ask=
```
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.