# Create A Shopping List

Creates a shopping list. Both Server Token and User Access Token are allowed to be used in this endpoint. In the case of Server Token, a list will not be linked to any user and it will be only possible to access it by id.

<mark style="color:green;">`POST`</mark> `https://graph.whisk.com/v1/lists`

#### Request Body

| Name     | Type   | Description                                                                                                                |
| -------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| name     | string | Shopping List name                                                                                                         |
| language | string | Language can be provided explicitly which will impact analysis on shopping list items. Default: `en`                       |
| recipes  | array  | References to `ShoppingListRecipePayload` recipes to add to a shopping list                                                |
| rawItems | array  | Ids of recipes. The cart will be generated based on recipe ingredients. The id can be represented by GraphID or recipe URL |
| items    | array  | List of `ShoppingListItemPayload` normalized items to add                                                                  |

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

```
```

{% endtab %}
{% endtabs %}

## Parameters

### ShoppingListRecipePayload

| ATTRIBUTE | TYPE   | DESCRIPTION                                          |
| --------- | ------ | ---------------------------------------------------- |
| id\*      | string | GraphId or URL of a Recipe                           |
| scale     | float  | Multiplier for default amounts in recipe: 0.5, 2 ... |

### ShoppingListItemPayload

| ATTRIBUTE | TYPE   | DESCRIPTION               |
| --------- | ------ | ------------------------- |
| quantity  | double | Item quantity             |
| unit      | string | Item unit (e.g. gram, ml) |
| name\*    | string | Item name (e.g. potato)   |
| comment   | string |                           |

## Response

| ATTRIBUTE     | TYPE                             | DESCRIPTION                             |
| ------------- | -------------------------------- | --------------------------------------- |
| id\*          | string                           |                                         |
| name\*        | string                           |                                         |
| primary       | boolean                          |                                         |
| createdTime\* | datetime                         | The time the Shopping List was created. |
| updatedTime\* | datetime                         |                                         |
| items         | array \[ShoppingListItemElement] |                                         |

## ShoppingListItemElement

| ATTRIBUTE      | TYPE           | DESCRIPTION               |
| -------------- | -------------- | ------------------------- |
| quantity       | double         | Item quantity             |
| unit           | string         | Item unit (e.g. gram, ml) |
| name\*         | string         | Item name (e.g. potato)   |
| comment        | string         |                           |
| brand          | string         |                           |
| analysis       | SLItemAnalysis |                           |
| recipe         | string         |                           |
| recipeOrdering | integer        |                           |
| createdTime    | datetime       |                           |
| combined       | array          |                           |

## SLItemAnalysis

| ATTRIBUTE     | TYPE            | DESCRIPTION                    |
| ------------- | --------------- | ------------------------------ |
| canonicalName | string          | Unique normalized product name |
| category      | ProductCategory |                                |

## ProductCategory

| ATTRIBUTE |   | TYPE   |   | DESCRIPTION |
| --------- | - | ------ | - | ----------- |
| name\*    |   | string |   |             |

### Request (adding raw items)

```bash
curl -X POST "https://graph.whisk.com/v1/lists" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <User-Access-Token>" \
  -d '{
    "name": "My Shopping List",
    "rawItems": [
      "200g pack smoked salmon",
      "2 slices sharp cheddar cheese",
      "1 tbsp salt and olive oil to serve"
    ]
  }'
```

### Request (adding items)

```bash
curl -X POST "https://graph.whisk.com/v1/lists" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <User-Access-Token>" \
  -d '{
    "name": "My Shopping List",
    "items": [
      {
        "quantity": 200,
        "unit": "g",
        "name": "smoked salmon"
      },
      {
        "quantity": 2,
        "unit": "slices",
        "name": "cheddar cheese",
        "comment": "extra mature"
      }
    ]
  }'
```

### Request (adding recipes)

```bash
curl -X POST "https://graph.whisk.com/v1/lists" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <User-Access-Token>" \
  -d '{
    "name": "My Shopping List",
    "recipes": [
      {
        "id": "https://www.bbcgoodfood.com/recipes/omelette-pancakes-tomato-pepper-sauce",
        "scale": 0.5
      },
      {
        "id": "9773cb7eca5d11e7ae7e42010a9a0035"
      }
    ]
  }'
```