Create a Cart

Create a Cart

POST https://graph.whisk.com/v1/carts

You can provide both recipeIdsor items alongside a retailerIdfor 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

200

{
  "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"
  }
}

Sample Request

curl -X POST "https://graph.whisk.com/v1/carts" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <Access-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 yolkcan 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.

You can find if we support matching for a retailer and able to create a cart here in the retailer’s list in Store Inventory column.

Body Parameters

ShoppingCartItem

ATTRIBUTE	TYPE	DESCRIPTION
storeItem	StoreItemValue
raw	RawItemValue

StoreItemValue

ATTRIBUTE	TYPE	DESCRIPTION
sku*	string	item identifier in Retailer
quantity	integer	number of items to checkout Default value: 1
source	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	store details
items*	array [CartItemResponse]	matched products
groups*	array [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

CartItemResponse

ATTRIBUTE	TYPE	DESCRIPTION
id*	string	unique cart item identifier
sourceList*	array [CartItemSource]	list of original ingredients related to the current item
product	CartProductOption	store item
combined	array [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	quantity of product items
price	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