Shopping Lists

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.

Example mutation and response:

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 AddShoppingListItems(
    $items: [ShoppingListsItemsInputType]!,
    $shoppingListId: Int!
) {
    shoppingListsItemsCreate(
        items: $items
        shoppingListId: $shoppingListId
    ) {
        shoppingListsItems {
            id
            productId
            variantId
            quantity
        }
    }
}

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:

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.

Example query and response:

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

• 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:

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.)

Changing a List’s Status

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

Example Request:

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:

mutation SubmitShoppingList(
    $shoppingListId: Int,
    ...
) {
    shoppingListsUpdate(
        id: $shoppingListId,
        shoppingListData: {
            ...
            status: 40
        }
    ) {
        ...
    }
}

It also applies to approving a shopping list:

mutation SubmitShoppingList(
    $shoppingListId: Int,
    ...
) {
    shoppingListsUpdate(
        id: $shoppingListId,
        shoppingListData: {
            ...
            status: 0
        }
    ) {
        ...
    }
}