Share purchase lists

Understand the ways that purchase lists are shared

There are two ways that purchase lists can be shared. These are the following:

As a non-account-based shopper, you share the list with other non-account-based shoppers - With this method, a non-account-based shopper who has created a purchase list provides one or more email addresses of other non-account-based shoppers with whom they wish to share the list.
As an account-based shopper, you share the list with other account-based shoppers within the context of the current account - With this method, an account-based shopper who has created a purchase list provides one or more email addresses of recipients within the current account with whom they wish to share the purchase list. The account information refers to an account to which both you and the owner(s) of the email address belong. You also can indicate whether the purchase list should be shared with all shoppers in the current account. If you share a purchase list with an account then all members of the account can see the purchase list. A purchase list is private to the owner unless you explicitly share it with other non-account-based shoppers or account-based shoppers.

Understand purchase list owners vs. list recipients

Purchase list owners and the recipients that they share the list(s) with have different capabilities as to how they can use the list.

As a purchase list’s owner (creator), you may:

Share the purchase list with other shoppers, and grant edit permission to recipients.
Edit the name and description of the purchase list.
Edit any account/site viewing restrictions on the purchase list (via API only).
Delete the purchase list.
See and edit the list of purchase list recipients.
View the purchase list’s “last modified” information. A list owner can always see who last modified the purchase list and when the last modification occurred.

As the recipient of a purchase list you may:

See the name and email address of the purchase list’s owner.
Modify the quantity of an item in the purchase list.
If granted edit access, add items to the purchase list or remove items from the purchase list.

Note: Any shopper (non-account-based shopper or account-based shopper) who tries to add an item(s) to an existing purchase list from Product Details or Order Details can only choose from purchase lists that they have created.

Copy the purchase list and become the owner of the copy so that you can share the copy with other shoppers. Refer to the user interface for a link to copy (and rename) the list.

Recipients of shared purchase lists are viewed and managed differently depending on the type of shopper who creates the list. If you are a non-account-based shopper who creates the purchase list being shared you can do the following with list recipients:

See a list of all recipients (i.e., email addresses) with whom you shared the purchase list.
Add a recipient.
Remove a recipient.
When adding one or more recipients, you can optionally add a comment that will be included in the email notification sent to recipients. This comment is not saved and is not subsequently viewable.

If you are an account-based shopper who creates the purchase list being shared you can do the following with list recipients:

See a list of all individual recipients (i.e., email address/account information pairs) with whom you have shared the purchase list.
In the shopper user interface, you can only see the email addresses of those with whom you have shared the purchase list in the current account context.
Add an individual recipient.
Remove an individual recipient.
See a list of all account recipients with whom you have shared the purchase list.

In the shopper user interface, you can only see whether you have shared the purchase list with the current account.

Add an account recipient (via API only, for accounts other than the current context).
Remove an account recipient (via API only, for accounts other than the current context).
When adding one or more recipients, you can optionally add a comment that will be included in the email notification sent to recipients. This comment is not saved and is not subsequently viewable.

Understand validation of shoppers chosen to receive lists

Commerce validates the following before making a purchase list visible and accessible to a non-account-based shopper or account-based shopper:

The shopper’s email address exists in Commerce.
The shopper’s type (non-account-based shopper or account-based shopper) matches the type of the shopper who created the purchase list.
The shopper is a recipient of the purchase list.
With an account-based shopper, that the customer belongs to the account with which the purchase list was shared, or to the account in the email address/account information pair with which the purchase list was shared.
The shopper’s account and site context adhere to any account and/or site context viewing restrictions assigned to the purchase list.

Understand which purchase list types can be viewed

With the functionality of purchase lists being extended so that they can be shared, a shopper (non-account-based shopper or account-based shopper) can see two types of purchase lists:

My Lists – This is a list of all purchase lists that a shopper owns (and that are available in the current account or site)
Lists Shared with Me – This is a list of all purchase lists shared with the shopper (and that are available in the current account or site context) including:
- Lists shared with the owner directly by email address
- For account-based shoppers only, lists shared with owner at the account level (i.e., by virtue of the owner’s membership in an account)

Information that can be seen in the My Lists list includes the following:

Purchase list name (this is a link that opens the list details)
An icon indicating whether the purchase list is shared or private
The number of items contained in the list

Information that can be seen in the Lists Shared with Me list includes the following:

Purchase list name (this is a link that opens the list details)
The purchase list owner’s name
The purchase list owner’s email address
The number of items contained in the list

Each list of collected lists is paginated depending on the amount of lists.

Each list also has a filter control that lets you filter on the following fields:

Purchase list name
Purchase list owner’s name (for Lists Shared with Me)
Purchase list owner’s email address (for Lists Shared with Me)
Placeholder text for the filter control on My Lists: “Filter by name”
Placeholder text for the filter control on Lists Shared with Me: “Filter by name, email, or owner”

Note: These are not typeahead filters.

You can also sort the list on the following fields (ascending and descending):

Purchase list name
Purchase list owner’s name - sorted by last name (for Lists Shared with Me)
Purchase list owner’s email address (for Lists Shared with Me)

Finally, you can switch between the following views in the Lists Shared with Me list:

All lists shared with you (the owner) in this account (the default)
Lists shared with all members of this account
Lists shared with you (the owner) individually

Assign edit access to shared purchase lists

When sharing purchase lists, you have the ability to assign edit access to the list recipients if you are the list creator. Edit permission allows a shared purchase list recipient to add items to the purchase list or remove items from the purchase list. Editing access permissions can differ depending on the type of shopper you are.

A list owner who is a non-account-based shopper can:

Set a default edit permission (yes or no) for the purchase list. The default for this setting is no edit access.
Set the edit permission (yes or no) for an individual recipient of the purchase list. The default for this setting is no edit access.

Note: An individual non-account-based shopper recipient’s permission, if explicitly set, takes precedence over the purchase list’s default permission.

A shared purchase list owner (creator) who is an account-based shopper can

Set a default edit permission (yes or no) for the purchase list for an account recipient. The default for this setting is no edit access.
Set the edit (yes or no) for an individual recipient (a member of the current account) of the purchase list – that is using an email address. The default for this setting is no edit access.

Note: The permission for the individual email address, if explicitly set, takes precedence over the purchase list’s default permission for the account.

Understand email notifications for recipients of shared lists

Recipients of shared lists receive email notification when they are chosen to share a list. The following occurs in the email notification process for people who are chosen as recipients of shared purchase lists:

When a purchase list owner adds an individual recipient to share the list, the recipient receives a notification email.
When a purchase list owner adds an account-based recipient, a single email notification is sent with all current members of the account Bcc’d on the email.
Emails are scheduled using the scheduler, rather than being sent immediately. See Notify Shoppers When Items are Back in Stock for more information on using the scheduler.

For more complete information on what occurs during the email notification process, the contents of the emails, and how to configure the email settings for shared purchase lists, refer to Configure Email Settings.

Make sure purchase list sharing is available for shoppers

To make sure that list sharing is available for both non-account-based shoppers and account-based shoppers, you just need to make sure that the correct purchase list widgets are used in the store. These widgets are already present in layouts for account-based shoppers, but need to be added for shoppers that are not account based.

Once the purchase list widgets are included in a store’s pages, purchase list sharing is automatically available. There is no need actually configure list sharing – you just need to have the correct widgets present.

Note: For additional information on how to use purchase list widgets in your store layouts, refer to Configure purchase lists.

As mentioned, for non-account-based shoppers, you must add the necessary widget to the correct layout from the Design area of the administration user interface to expose the feature (these widgets are already present in layouts for account-based shoppers).

Use the following steps to add the widgets for non-account-based shoppers:

Login as the Administrator.
Open the Design page.
Search for the “Profile Layout” on the Layout page.
Open it for editing in the Grid View.
Find the “Profile Navigation (shared)” widget and open its Settings.
Add another row in it by clicking on “Add More Rows”.
In the first column add “purchaseListsText” and in the second column add “/purchaselists”.
Click on Save and publish these changes.

To check and make sure that the introduction of the widget to layout has made the creation of purchase lists available, do the following:

Login as to the store as a non-account-based shopper.
Click My Account at the top of the user interface.
On the My Account Page, click on Purchase Lists. At this page will see the options to:
- Create a purchase list
- Share a purchase list after you have created it by providing an email address.
- Set edit access permissions for the shared list.
- Copy an existing list for sharing, renaming, etc.
Be sure to save any changes or additions made to that page.

Add products to a list from the search box on the Purchase List details page

To have the ability to add products to your list from the search box on the Purchase List details page, use the following steps:

Login as the Administrator.
Open the Catalogs page.
Click Manage Catalogs > Product Types > Base Product
Click SKU Properties and click on edit the ID property.
Check Allow property to be searched.
Click on Save and Publish that change.
In the Search area of the administration user interface, go to Searchable Field Ranking.
Open the Typeahead ranking.
Add the SKU ID field.
Click on Save and Publish that change.

You should now be able to use the search box in the Purchase List details page to search for a product by its SKU ID.

Add products to your list from the Product details page

To have the ability to add Products to your purchase list from the Product details page, use the following steps:

Login as the Administrator.
Open the Design page.
Search for the Product Layout.
Open it for edit in the Grid View.
Look for the Product Details Widget and open its Settings.
From the pull-up menu for Element Library, pick the Add To Purchase List element (widget) and place it in the blank section above.
Click on Save and Publish these changes.

After having completed these steps, you can add to an existing purchase list or choose to create a new one when you open the product details page for a product. For additional information on how to enable purchase lists refer to Configure purchase lists.

Share a purchase list and specify edits permissions

To share purchase lists and specify edit permissions, required widgets need to conditionally display fields slightly differently for a non-account-based shopper as opposed to an account-based shopper who has created a purchase list. This process can be described as follows:

If you are a non-account-based shopper who created the purchase list then you can
- Indicate whether the purchase list should be shared with all shoppers. The default for this global sharing is False.
- If you wish to share the purchase list with all shoppers, optionally specify a global edit permission (yes or no) for the recipients. The default for the global edit permission is No / False.
- Provide one or more email addresses of shoppers with whom to share the purchase list.
- For each email address of a recipient, optionally specify an edit permission (yes or no). This individual edit permission, if present, overrides the global edit permission.
- When adding one or more recipients, optionally add a comment that will be included in the email notification sent to recipients. This comment is not saved and is not subsequently viewable.
If you are an account-based shopper who created the purchase list, then you can
- Indicate whether the purchase list should be shared with all shoppers in the current account. The default for this account-level sharing is False.
- If you share the purchase list at the account level, optionally specify an account-level edit permission (yes or no). The default for the account-level edit permission is No / False.
- Provide one or more email addresses of shoppers with whom to share the purchase list. The purchase list will be shared with each of them in the context of Monica’s current account context.
- For each email address of a recipient, optionally specify an edit permission (yes or no). This individual edit permission, if present, overrides the account-level edit permission.
- When adding one or more recipients, optionally add a comment that will be included in the email notification sent to recipients. This comment is not saved and is not subsequently viewable.

Both non-account-based shoppers and account-based shoppers can see the list of email addresses (and accounts, in an account-based shopper’s case) with which they have shared a purchase list.

Both non-account-based shoppers and account-based shoppers can remove an email address (or an account, in an account-based shopper’s case) from the list of recipients.

When a non-account-based shopper or an account-based shopper delete a purchase list that is shared, both will get a confirmation dialog that announces that the purchase list is shared and will ask them if they really want to delete it. Cancel and Delete buttons allow them to make either choice.

Understand the purchase list cleanup process

Behind the scenes, Commerce will periodically run a cleanup process that:

Updates recipient lists for purchase lists owned by shoppers whose account memberships have changed
Customers can configure how often the process runs.

See Work with the purchase list API for more information on removing purchase lists.