> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Shopping Lists

Plan: B2B Developer

Lesson 11 of 18 · 30 min

## Introduction

Shopping lists allow company users to collaborate on items to be purchased. Junior Buyers can create shopping lists, but they need approval from a qualified user, like a Senior Buyer or Admin user.

Company users can share shopping lists with teammates, turn them into quotes, or add items to  cart for checkout.

## Creating a Shopping List

The `shoppingListsCreate` mutation creates a new shopping list.

> **Info**
>
> The `shoppingListsCreate` mutation is available to any of the built-in user roles, or a custom role with the "Shopping list - Create, edit, delete" permission.

### Example mutation and response:

```graphql showLineNumbers={false}
mutation CreateShoppingList(
    $name: String!,
    $description: String!,
    $status: Int!
) {
    shoppingListsCreate(
        shoppingListData: {
            name: $name,
            description: $description,
            status: $status
        }
    ) {
        shoppingList {
            id
            name
            description
            status
        }
    }
}
```

### Shopping List Status

The statuses that apply to a shopping list include:

* **0** - A list that's been approved
* **30** - A list in "draft" status, still not submitted for approval
* **40** - A list that's waiting for approval

A user with the Senior Buyer role or higher, or a custom role with the "Shopping list - Approve draft status list" permission, can create a shopping list with the 0 (approved) status initially, while other users must create a list with a different status. The 30 (draft) status is appropriate until the user has confirmed they are ready for the shopping list to be submitted for approval.

## Obtaining Product Details

Adding items to a shopping list requires the following details of the products in question:

* **Product ID**
* The specific **variant ID** (this includes the base variant for simple products)

If necessary, these details can be fetched using the `productsSearch` query, as described for the quoting process.

## Adding Items to a List

With the ID of a shopping list and the product ID and variant ID of relevant products, the `shoppingListsItemsCreate` mutation is used to add items to a list.

### Example mutation and variables:

#### Mutation

```graphql showLineNumbers={false}
mutation AddShoppingListItems(
    $items: [ShoppingListsItemsInputType]!,
    $shoppingListId: Int!
) {
    shoppingListsItemsCreate(
        items: $items
        shoppingListId: $shoppingListId
    ) {
        shoppingListsItems {
            id
            productId
            variantId
            quantity
        }
    }
}
```

#### Response

```json showLineNumbers={false}
{
    "shoppingListId": {{shopping_list_id}},
    "items": [
        {
            "productId": 10,
            "variantId": 15,
            "quantity": 10,
            "productNote": "Highest priority"
        },
        ...
    ]
}
```

The `productNote` field is designed for custom notes applicable to the item in the context of the specified shopping list.

The `shoppingListsItemsUpdate` mutation is also available and accepts data similar to `shoppingListsItemsCreate` but including the ID of a specific item to update.

### Example Request:

```graphql showLineNumbers={false}
mutation UpdateShoppingListItem(
    $itemId: Int!,
    $shoppingListId: Int!,
    $itemData: ShoppingListsItemsUpdateInputType!
) {
    shoppingListsItemsUpdate(
        itemId: $itemId,
        shoppingListId: $shoppingListId,
        itemData: $itemData
    ) {
        shoppingListsItem {
            id
            productId
            variantId
            quantity
        }
    }
}
```

## Fetching List Details

The `shoppingLists` query is used to fetch all lists a user has access to.

> **Info**
>
> The `shoppingLists` and `shoppingList` queries are available to any of the built-in user roles, or a custom role with the "Shopping list - View" permission. Which lists a user can fetch depends on the value of this permission setting, as described below.

### Example query and response:

#### Query

```graphql showLineNumbers={false}
query GetShoppingLists {
    shoppingLists {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                id
                createdAt
                name
                description
                status
                customerInfo {
                    firstName
                    lastName
                    userId
                    email
                    role
                }
                isOwner
                products {
                    edges {
                        node {
                            id
                            productId
                            variantId
                            quantity
                            productSku
                            productNote
                        }
                    }
                }
            }
        }
    }
}
```

#### Response

```json showLineNumbers={false}
{
    "data": {
        "shoppingLists": {
            "pageInfo": {
                "hasNextPage": true,
                "hasPreviousPage": false,
                "startCursor": "YXJy...",
                "endCursor": "YXJy..."
            },
            "totalCount": 7,
            "edges": [
                {
                    "node": {
                        "id": "987654",
                        "createdAt": 1767160800,
                        "name": "Fall Re-stock",
                        "description": "These items are needed for the fall re-stock.",
                        "status": 30,
                        "customerInfo": {
                            "firstName": "Jack",
                            "lastName": "Doe",
                            "userId": 1234568,
                            "email": "jackdoe@example.com",
                            "role": "2"
                        },
                        "isOwner": false,
                        "products": {
                            "edges": [
                                {
                                    "node": {
                                        "id": "567890123",
                                        "productId": 10,
                                        "variantId": 15,
                                        "quantity": 10,
                                        "productSku": "FCY-LMP",
                                        "productNote": "Highest priority"
                                    }
                                },
                                ...
                            ]
                        }
                    }
                },
                ...
            ]
        }
    }
}
```

* The `shoppingLists` query supports standard pagination arguments.
* Other filter arguments include `status`, `createdBy`, and `email`.
* `customerInfo` contains the details of the user who created the quote.
* `isOwner` is TRUE if the owner of the current authentication token is the same as the user who created the quote, FALSE otherwise.

The `shoppingList` query fetches a single list. The result type of this query is different than the type returned by `shoppingLists`. This result type supports fields with more details of the list and its items, including price totals.

### Example Request:

```graphql showLineNumbers={false}
query GetShoppingList(
    $shoppingListId: Int!
) {
    shoppingList(
        id: $shoppingListId
    ) {
        id
        createdAt
        name
        description
        status
        customerInfo {
            firstName
            lastName
            userId
            email
            role
        }
        isOwner
        grandTotal
        totalDiscount
        totalTax
        products {
            edges {
                node {
                    id
                    productId
                    variantId
                    quantity
                    productName
                    baseSku
                    variantSku
                    basePrice
                    discount
                    tax
                    productUrl
                    primaryImage
                    productNote
                }
            }
        }
    }
}
```

### Permissions and Viewing

Like several company user permissions, the permission related to fetching shopping lists ("Shopping list - View") can be set to "User" or "User team" for a given role. Those with the "User" value for this permission can only access the records they created, while those with "User team" can access all records belonging to the company.

This means that Junior Buyers, for example (with "User" set for "Shopping list - View"), can only fetch their own shopping lists, while Senior Buyers and above (with "User Team") can fetch those belonging to any company user.

While more privileged users can fetch all of a company's shopping lists, it's often helpful to filter them further. Remember that the shopping list status 30 indicates "draft" status, meaning the list's owner has not yet submitted it for approval.

For this reason, the default B2B Edition Buyer Portal restricts the shopping lists that appear in the UI as follows:

* For users with the **"Submit draft status list for approval"** permission (or restriction, in this case), no status filter is applied. Users can see either all shopping lists ("User team") or only their own ("User"), even those in draft status.
* For users **without this restriction**, shopping lists are filtered on the 0 (approved) and 40 (ready for approval) statuses, meaning lists still in draft status are hidden. (When such users create shopping lists, status is automatically set to approved.)

> **Info**
>
> To inspect the specific permissions assigned to a user's role, like the Buyer Portal does in this use case, see the GraphQL Playground for the details of the `companyRole` query.

## Changing a List's Status

The `shoppingListsUpdate` mutation is used to update the details of a list.

### Example Request:

```graphql showLineNumbers={false}
mutation SubmitShoppingList(
    $shoppingListId: Int,
    $name: String!,
    $description: String!,
    $status: Int!
) {
    shoppingListsUpdate(
        id: $shoppingListId,
        shoppingListData: {
            name: $name,
            description: $description,
            status: $status
        }
    ) {
        shoppingList {
            id
            name
            status
        }
    }
}
```

All three of the key arguments (`name`, `description`, and `status`) are required, so your application will need to track the existing values and re-transmit any that remain unchanged.

This is the key mutation to use when moving a shopping list through the phases of the approval workflow, as this involves simply updating the `status`.

This applies to **submitting a list for approval**:

```graphql showLineNumbers={false}
mutation SubmitShoppingList(
    $shoppingListId: Int,
    ...
) {
    shoppingListsUpdate(
        id: $shoppingListId,
        shoppingListData: {
            ...
            status: 40
        }
    ) {
        ...
    }
}
```

> **Info**
>
> Only Junior Buyers, or custom roles with the "Submit draft status list for approval" permission, can set this status.

It also applies to **approving a shopping list**:

```graphql showLineNumbers={false}
mutation SubmitShoppingList(
    $shoppingListId: Int,
    ...
) {
    shoppingListsUpdate(
        id: $shoppingListId,
        shoppingListData: {
            ...
            status: 0
        }
    ) {
        ...
    }
}
```

> **Info**
>
> Only Senior Buyers or above, or custom roles with the "Approve draft status list" permission, can set this status.