Learning PathModule

Shopping Lists for B2B purchasing

Use Shopping Lists as a core B2B resource for shared purchasing lists, saved order templates, and quick reorder workflows.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Explain how Shopping Lists support shared and repeat B2B purchasing.

  • Design Shopping List permissions for a Business Unit using the My and Others model.

  • Convert a Shopping List into a Cart, applying the buyer's distribution Channel so prices resolve.

Horizon Hotels reorders the same room-electronics kit every month: a fixed set of TVs, kettles, and chargers across dozens of properties. Rebuilding that basket by hand each time is the friction B2B buyers want to remove. In commercetools, the Shopping List is the resource that makes standard baskets, saved templates, and quick reorder workflows possible. In B2B, it becomes a shared, permissioned resource within a Business Unit. For the full Shopping List API lifecycle, including CRUD, querying, and concurrency, see the Implement carts and shopping lists path.

Why Shopping Lists are a core B2B resource

In B2C a Shopping List is often a personal wishlist. In B2B it does heavier work:

  • Procurement templates: a standing basket the buyer reorders on a cadence (Horizon Hotels' monthly kit).
  • Project lists: a basket assembled over time for a specific job (Pacific Property Group building a per-development list).
  • Shared lists: one Associate curates the list, another places the order, reflecting the split between who specifies and who buys in a procurement team.

The shared case is what makes Shopping Lists a B2B modeling concern rather than a convenience feature: access to a list must follow the buyer organization's roles, not just the individual who created it.

The My and Others permission model

Shopping List access in B2B is governed by Associate permissions, which come in My and Others pairs. This is the same model you designed roles around in Configure associate access. My permissions apply to lists the Associate owns; Others permissions apply to lists owned by other Associates in the Business Unit.
Shopping List permissions follow the same action pairs for viewing, creating, updating, and deleting Shopping Lists. Each action has a My permission for Shopping Lists owned by the Associate and an Others permission for Shopping Lists owned by other Associates in the Business Unit. For the complete list of permission enum values, see Permission.
To model a shared purchasing list where a procurement lead curates and a buyer orders, give the buyer role ViewOthersShoppingLists so the buyer can read the lead's lists, and keep curation permissions (CreateMyShoppingLists, UpdateMyShoppingLists) on the lead's role.
Others does not imply My. Granting ViewOthersShoppingLists lets an Associate see other people's lists but not their own; for that they also need ViewMyShoppingLists. Design each role with both halves of the pair in mind; omitting My is a common cause of "I can see everyone's lists but not mine" support tickets.

Creating a Shopping List as an Associate

B2B Shopping Lists are created through the as-associate endpoint, scoped to a Business Unit. The platform enforces the relevant permission server-side, using the same Permission Gate you met in Module 2.
POST /{projectKey}/as-associate/{associateId}/in-business-unit/key=horizon-hotels/shopping-lists HTTP/1.1
Content-Type: application/json

{
  "name": { "en-AU": "Monthly room-electronics kit" },
  "lineItems": [
    { "sku": "ZET-TV-43", "quantity": 12 },
    { "sku": "ZET-KETTLE-1L", "quantity": 12 },
    { "sku": "ZET-USBC-65W", "quantity": 24 }
  ]
}

Two details matter for B2B:

  • The endpoint requires the manage_shopping_lists:{projectKey} OAuth scope, and the Associate's role must include the matching permission (CreateMyShoppingLists or CreateOthersShoppingLists). Without it the platform returns 403 Forbidden.
  • The businessUnit is taken from the URL path. Any businessUnit field in the request body is ignored, so the list always belongs to the Business Unit you addressed.
Shopping Lists can also be scoped to a Store through the in-store endpoints, which keeps a buyer's lists within the same commercial context as their Carts and Orders.

From list to Cart to order

A Shopping List is a template, not an order. To buy, you convert the list into a Cart with the addShoppingList update action, which copies every Line Item from the list onto the Cart in one call.
POST /{projectKey}/as-associate/{associateId}/in-business-unit/key=horizon-hotels/carts/{cartId} HTTP/1.1
Content-Type: application/json

{
  "version": 1,
  "actions": [
    {
      "action": "addShoppingList",
      "shoppingList": { "typeId": "shopping-list", "key": "monthly-room-electronics" },
      "distributionChannel": {
        "typeId": "channel",
        "key": "horizon-hotels-pricing"
      }
    }
  ]
}
The distributionChannel on the action is the link to Configure B2B pricing: it sets the buyer's distribution Channel on every Line Item added from the list, so each item resolves the buyer's negotiated Channel-scoped Price rather than an unscoped one. Pass the same Channel the buyer's Store carries, and the reorder lands at the right price automatically.
This list-to-Cart conversion is also the entry point to the quote flow. For large or custom orders, a buyer can build a list, convert it to a Cart, and then raise a Quote Request from that Cart for negotiation. You will follow the full quote lifecycle in the Implement B2B purchase flows module.

Worked example: shared lists across Zen Electron Trade buyers

The three buyers use Shopping Lists differently, and each maps to a permission and scoping decision:

  1. Horizon Hotels (self-service) keeps one standing "monthly kit" list. A single Buyer role with CreateMyShoppingLists, UpdateMyShoppingLists, and ViewMyShoppingLists is enough; the same person curates and orders.
  2. Pacific Property Group (hybrid) runs per-development project lists where a project lead curates and division buyers order. Give the lead's role the My create and update permissions, and give the buyers' role ViewOthersShoppingLists so they can order from the lead's lists without editing them.
  3. Atlas Corporate Solutions (quote-based) assembles large lists that become Quote Requests. Buyers build lists, convert them to Carts with the division's distribution Channel, and hand off to the quote flow. List permissions sit with the requesting role, while approval and quote permissions (covered later) sit elsewhere, preserving separation of duties.
In every case the rule is the same: decide who curates and who orders, then assign the My and Others halves of each permission accordingly, and scope lists to the buyer's Store so they share the buyer's commercial context.

Key takeaways

  • In B2B, Shopping Lists model procurement templates, project lists, and shared lists where one Associate curates and another orders.
  • Shopping List access uses paired My/Others permissions; Others never implies My, so design both halves into each role.
  • Create B2B Shopping Lists through the as-associate and in-business-unit path segments; the Business Unit comes from the path and any businessUnit in the body is ignored.
  • Convert a list to a Cart with the addShoppingList action, passing the buyer's distributionChannel so Line Items resolve the negotiated Price.
  • A list converted to a Cart is also the starting point for a Quote Request in the Implement B2B purchase flows module.

Test your knowledge