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

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

raw

StoreItemValue

ATTRIBUTE

TYPE

DESCRIPTION

sku*

string

item identifier in Retailer

quantity

integer

number of items to checkout Default value: 1

source

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*

store details

items*

array []

matched products

groups*

array []

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

CartItemResponse

ATTRIBUTE

TYPE

DESCRIPTION

id*

string

unique cart item identifier

sourceList*

array []

list of original ingredients related to the current item

product

store item

combined

array []

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*

quantity of product items

price

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

PreviousCarts NextUpdate Cart Item

Last updated 4 years ago