# Shopping Lists for B2B purchasing

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](/api/projects/shoppingLists.md) 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](/learning-implement-carts-and-shopping-lists/implement-shopping-lists/overview.md) 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](/api/projects/associate-roles.md), which come in **My** and **Others** pairs. This is the same model you designed roles around in [Configure associate access](/learning-model-b2b-commerce/configure-associate-access/overview.md). 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](/api/projects/associate-roles.md#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.

```http
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](/api/projects/shoppingLists.md#get-shoppinglist-in-store), 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](/api/projects/carts.md) with the `addShoppingList` update action, which copies every Line Item from the list onto the Cart in one call.

```http
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](/learning-model-b2b-commerce/configure-b2b-pricing/company-specific-pricing.md): 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](/learning-model-b2b-commerce/implement-b2b-purchase-flows/overview.md) 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.

## Related pages

- [Area overview page with navigation](/learning-model-b2b-commerce.md)
- [Previous page: Faceting and filtering on price](/learning-model-b2b-commerce/discover-and-order-products-in-b2b/faceting-and-filtering-on-price.md)
- [Next page: Learning check](/learning-model-b2b-commerce/discover-and-order-products-in-b2b/learning-check.md)