Skip to main content

Shopping Lists template

Export, create, and update BigCommerce B2B Edition shopping lists and their items with Shift.

tip

Start with an export and use its Basic and Items sheets as your import template.

Quick start​

To create a list, follow the creating shopping lists guide or download the minimal creation example.

To see every supported export column, download the full shopping list export example.

Export shopping lists​

  1. Choose Shopping Lists in Shift and start a new export.
  2. On the Filter step, choose User and select a B2B company user by name. You must select one user, and only one user can be selected per export.
  3. On the Columns step, choose the list fields under Basic and the product fields under Items. Include ID on both sheets if you plan to update the exported lists and items.
  4. Complete the export and download the spreadsheet.

The chosen user's BigCommerce B2B role affects which lists the export can return. A junior buyer can see lists they created, but no one else's. A senior buyer or company administrator can see the company's Approved and Ready for approval lists, including lists submitted by junior buyers. Choose the user whose access matches the lists you need, and check the exported file before making changes.

Import and export columns​

The Basic sheet has one row per shopping list. The Items sheet has one row per item. Shopping List ID links an item to an existing list. For a new list without an ID, use Shopping List Name to link its item rows to the new Basic row. A name cannot identify an existing list for an update.

Basic columns​

ColumnDescription
ModeImport mode for the shopping list. See import modes.
IDBigCommerce shopping list ID. Keep this value to update or delete an existing list. If it is blank, Shift creates a new list, even when its name matches an existing list.
NameShopping list name. Required when creating a list; editable on an existing list. Also links Items rows to a new list that has no ID yet.
DescriptionShopping list description.
StatusRequired when creating a list. Use Approved, Deleted, Draft, or Ready for approval (or the corresponding values 0, 20, 30, 40).
Company IDB2B company ID associated with the list. Read only.
User IDB2B buyer user ID. Required when creating a list.
Channel IDStorefront channel ID, when present.
Channel NameStorefront channel name. Read only.
Created AtCreation date and time. Read only.
Updated AtLast update date and time. Read only.

Items columns​

ColumnDescription
Shopping List IDLinks this row to the shopping list on the Basic sheet. Required when updating an existing list.
Shopping List NameMatches an item row to a new Basic row when the list has no ID. It does not replace Shopping List ID for updates.
IDBigCommerce item ID. Keep it to update an existing item; leave it blank to add a new item.
Product IDBigCommerce product ID used to identify a new item.
Product SkuProduct SKU included on export for readability. It does not identify an item on import.
Variant IDBigCommerce variant ID used to identify a new item when the product has variants.
Variant SkuVariant SKU included on export for readability. It does not identify an item on import.
QuantityItem quantity. Set an existing item's quantity to 0 to remove it from the usable list.
Sort OrderPosition of the item in the list.
Product NoteNote attached to the item.
Option IDProduct option ID, when applicable.
Option ValueProduct option value, when applicable.
Created AtItem creation date and time.
Updated AtItem last update date and time.

For a new item, include Product ID and Quantity. Include Variant ID when the product has variants. Shift's current import validation may also require Variant ID for products without variants; if validation rejects the row, supply the product's variant ID. For an existing item, its ID identifies the item to update.

Update a list or its items​

Keep the shopping list ID on the Basic sheet and Shopping List ID on its Items rows. You can then change the Name, edit an item's Quantity or Product Note, or add an item by leaving its item ID blank. To create an entirely new shopping list, leave its list ID blank and provide a Name, Status, and User ID. On the Items sheet, use the same Shopping List Name to attach new items to it.

warning

Do not remove the shopping list ID from a row you intend to update. Shift cannot match by shopping list name, so a row without the ID creates a new shopping list.

Import modes​

Use the import modes guide for the Mode column on the Basic sheet. This controls whether Shift merges, creates, updates, replaces, deletes, or skips the shopping list itself.

ModeAction
MergeExisting items are updated. New items are created. Missing columns or empty column values are ignored.
This is the default mode.
UpdateExisting items are updated. New items are ignored. Missing columns or empty column values are ignored
CreateNew items are created. Existing items are ignored.
ReplaceExisting items are deleted and recreated. New items are created. This is the same as a Delete followed by a Merge.
DeleteExisting items are deleted.
SkipThis item is ignored

You can also choose an Items import mode separately. On an existing list:

Items modeEffect
MergeUpdate items with matching item IDs and add new items. Other items remain as they are. This is the default.
CreateAdd new items only. Existing item IDs are ignored.
UpdateUpdate items with matching item IDs only. New items are ignored.
ReplaceKeep the shopping list, apply the imported items, and remove existing items omitted from the file by sending quantity 0.
DeleteSet the quantity of matching existing items in the file to 0.
info

For item Replace and Delete, Shift sends quantity 0 to remove affected items from the shopping list. Replacing Items keeps the shopping list itself and its ID.

Export filters​

Shopping list exports use the User filter. Select one B2B buyer user by name for each export. The BigCommerce list endpoint determines visibility from that user's role and the lists' statuses.

BigCommerce references​