---
title: Product collections
slug: product-collections
abstract: Product collections enable buyer users to create and manage personalized product lists
content_type: concept
audience: \[developer, business-user, architect]
---
# Product collections

Product collections enable buyer users to create and manage personalized product lists. This feature provides flexible list management capabilities that support various e-commerce scenarios and user experiences.

## Use cases

### Save for later

- Move products from active orders
- Preserve shopping intentions
- Simplify future purchases
- Track desired items

### Favorite products

- Mark preferred items
- Quick access to frequent purchases
- Personalized product lists
- Simplified reordering

### Custom wishlists

- Create multiple lists
- Organize by purpose
- Share product selections
- Track desired items

## Key features

### Visibility control

Product restrictions:

- Only visible products can be added

  ```
  GET me/products
  ```

- Follows standard visibility rules
- Respects user permissions
- Maintains data security

### Access management

Current limitations:

- Collections visible to creator only
- No public list sharing
- No organization-wide visibility
- No user-to-user sharing

Future possibilities:

- Public list functionality
- Organization-wide sharing
- User-specific sharing
- Controlled visibility

### Collection limits

System boundaries:

- 500 products per collection
- Unlimited collections per user
- Efficient list management
- Optimized performance

## ProductCollection resource

Core collection definition:

```json
{
  "ID": "",
  "Name": "",
  "xp": {}
}
```

Properties:

- ID: Unique identifier
- Name: Collection title
- xp: Extended properties

## API endpoints

### Collection management

Basic operations:

- `GET v1/me/productcollections`
  - List all collections
  - View collection details
  - Access personal lists

- `GET v1/me/productcollections/{productCollectionID}`
  - Retrieve specific collection
  - View collection details
  - Access list contents

- `POST v1/me/productcollections`
  - Create new collection
  - Set collection name
  - Configure properties

- `PUT v1/me/productcollections/{productCollectionID}`
  - Update entire collection
  - Modify all properties
  - Replace configuration

- `PATCH v1/me/productcollections/{productCollectionID}`
  - Partial collection updates
  - Modify specific properties
  - Preserve other settings

- `DELETE v1/me/productcollections/{productCollectionID}`
  - Remove collection
  - Delete all entries
  - Clean up resources

### Product management

List operations:

- `GET v1/me/productcollections/{productCollectionID}/products`
  - View collection contents
  - List included products
  - Follow [product visibility rules](https://doc.sitecore.com/ordercloud/en/developers/platform/product-visibility.html)

Item operations:

- `PUT v1/me/productcollections/{productCollectionID}/{productID}`
  - Add product to collection
  - Create new entry
  - Update list contents

- `DELETE v1/me/productcollections/{productCollectionID}/{productID}`
  - Remove product from collection
  - Delete entry
  - Update list contents

## Collection entries

### New capabilities

December 2024 enhancements:

- Entry creation endpoint:

  ```
  POST v1/productcollections/{productCollectionID}/products
  ```

Required fields:

- ProductID: Target product

Optional features:

- ListOrder: Custom sorting
- DateAdded: Automatic timestamp

### Entry management

Sorting options:

- Custom list order
- Addition date
- Product attributes
- User preferences

Use cases:

- Wishlist organization
- Saved item management
- Priority ordering
- Custom arrangements

## Implementation considerations

### Collection design

Best practices:

1. Plan collection structure
2. Define naming conventions
3. Consider xp requirements
4. Document limitations

### Product handling

Guidelines:

1. Verify product visibility
2. Check collection limits
3. Manage entry ordering
4. Handle removals

### User experience

Recommendations:

1. Clear collection naming
2. Intuitive organization
3. Easy product management
4. Efficient navigation

## Future enhancements

Planned capabilities:

- Public list sharing
- Organization visibility
- User-specific sharing
- Enhanced sorting

For additional features, see regular platform updates.

## Product collection enhancements

The Product Collections feature has been enhanced with new functionality to support additional use cases beyond private product lists. These enhancements include new endpoints and an `AccessLevel` property that provides greater flexibility in implementing ProductCollections in your marketplace.

### Implementation scenarios

#### Marketplace insights

Marketplace Owners and Suppliers can now view `ProductCollections` with the `ProductCollectionReader` role to understand which products customers are saving to their collections.

#### Shared household lists

Enable customers to create grocery lists and invite household members to view and manage them.

#### Holiday wishlists

Allow customers to create `Sharable` holiday wish lists that family members can view.

### Access level property

The `AccessLevel` property defines who can view and interact with a product collection:

#### Private collections

- Default access level
- Collection owners control access
- Owners can grant access through `ProductCollectionInvitations`
- Limited to users within the same buyer organization

#### Public collections

- Accessible to all users in the buyer organization
- Includes anonymous (unregistered) users
- Available through `GET v1/me/productcollections`
- Maintains organization boundaries

#### Shareable collections

- Accessible by collection ID
- Available to all users in the buyer organization
- Includes anonymous (unregistered) users
- Access via `GET v1/me/productcollections/{productCollectionID}`
- Maintains organization boundaries

### ProductCollectionReader role

This new role provides different capabilities based on user type:

#### Marketplace owner access

- View collections across the marketplace
- Access all buyer user collections
- Complete visibility of collection contents

#### Supplier access

- View collections for authorized buyers
- See entries for owned/authorized products
- Limited to relevant product visibility

#### Buyer user access

- View collections within their organization
- See entries based on product visibility
- Follow standard [visibility rules](https://doc.sitecore.com/ordercloud/en/developers/platform/product-visibility.html)

#### Associated endpoints

The `ProductCollectionReader` role enables access regardless of `AccessLevel`, within defined limitations:

```http
GET v1/buyers/{buyerID}/productcollections
GET v1/buyers/{buyerID}/productcollections/{productCollectionID}
GET v1/buyers/{buyerID}/productcollections/{productCollectionID}/products
```

### ProductCollectionInvitation resource

This new resource enables collection owners to grant access to their private collections:

```json
{
  "ProductCollectionInvitation": {
    "ID": "",
    "Name": "",
    "Admin": false,
    "Accepted": false,
    "ExpirationDate": "",
    "xp": {}
  }
}
```

#### Properties

- ID: System-generated identifier for accepting/declining invitations
- ExpirationDate: Defaults to 30 days, maximum 365 days
- Admin: When true, allows invitee to manage collection entries
- xp: Stores invitation-related information (name, email, etc.)

#### Implementation notes

- Each user needs a separate invitation
- Invitations can only be accepted once
- System validates organization membership
- Use pre-webhooks for additional validation
- Extended properties do not affect access control

#### Associated endpoints

All endpoints require only the `Shopper` role:

```http
POST v1/me/productcollections/{productCollectionID}/invitations
DELETE v1/me/productcollections/{productCollectionID}/invitations/{invitationID}
GET v1/me/productcollections/{productCollectionID}/invitations
POST v1/me/productcollections/{productCollectionID}/invitations/accept/{invitationID}
POST v1/me/productcollections/{productCollectionID}/invitations/decline/{invitationID}
```

#### Endpoint behaviors

- POST: Creates new invitation
- DELETE: Revokes access or prevents acceptance
- GET: Lists all invitations
- Accept/Decline: Limited to registered users in organization

### Message senders

#### Built-in notifications

Two new message sender types:

- `ProductCollectionInvitationAccepted`
- `ProductCollectionInvitationDeclined`

These notify collection owners when invitations are accepted or declined.

#### Custom notifications

- No built-in sender for new invitations
- Use webhooks for custom invitation emails
- Implement validation as needed
- Configure based on business requirements

## The possibilities of product collections

Product Collections provide benefits for buyers that enhance their shopping experience and increase sales. A saved list of products helps buyers by:

- Keeping products top-of-mind for future purchases
- Saving time by providing quick access to needed items
- Supporting complex shopping projects that require planning
- Enabling peer-to-peer product sharing and recommendations

Businesses can gain insights from saved products to create targeted marketing campaigns. Integration with [Sitecore Search](https://www.sitecore.com/platform/search) helps understand buyer preferences and deliver relevant shopping experiences.

### Private lists: Favorites, Save for Later, or Custom lists

Authenticated shoppers can create personal Product Collections to save products to their account:

- "Save for Later" option for cart items they're not ready to purchase
- Quick-save buttons (heart/star) on product cards for frequently purchased or favorite items
- Custom named lists for specific projects (e.g., "Game Room" for home furnishing projects)

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/e004b5079de34bb8b99e24849d78991f.png)

### Privately shared wishlists

Product Collections can be shared with specific users. For example, creating shared grocery lists or holiday wish lists. The `AccessLevel` property controls sharing:

- `AccessLevel:Private` allows the creator to invite specific users:
  - `Admin:False` - View-only access
  - `Admin:True` - Full edit access (add/delete products, rename list, invite others)

Invited users must accept the invitation to access the Product Collection.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/70a6e078af2c465e8ed1207440de52e4.png)

### Shareable wishlists

Creating a Product Collection with `AccessLevel:Shareable` generates a shareable link. Example use case: A teacher sharing classroom supply needs with student families via a link:

`https://www.yourwebsitehere.com/productcollection/view/2dcf59c0-6cca-11ec-b7a2-a7c693c3c9`

This eliminates the need for individual invitations.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/ba90071c9179448aa4f78fd92460ca09.png)

### Gift registry

Wedding and baby registries use Product Collections with `AccessLevel:Public`. These lists are searchable and accessible to anyone. Extended properties (xp) can store:

- Recipient names
- Event date
- Location
- Quantity requested per item
- Purchase tracking

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/0b6c2ff6f2274673925be978ec228e57.png)

### Buying lists

For business scenarios, like a restaurant chain District Manager distributing monthly marketing materials, Product Collections simplify ordering. Create a list of required items and share it with purchasing staff using Private or Shareable `AccessLevel`.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/cf6ccc9fc57e4240aa88443ce0941933.png)

## Building a wishlist feature with product collections

### Implementation requirements

#### Prerequisites

Product collections implementation requires:

- Active buyer user account
- Orderable products with buyer visibility

#### Environment assumptions

This guide uses:

- US-West sandbox environment
- Example product ID: `enterprise-product-id`
- Product configured for buyer ordering and visibility

### Implementation steps

#### Create wishlist collection

First, create a Product Collection to serve as the wishlist:

::::codetabs
:::codetab{title="HTTP"}

```http
POST sandboxapi.ordercloud.io/v1/me/productcollections HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

```json
{
  "ID": "wishlist",
  "Name": "Wishlist"
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Me } from "ordercloud-javascript-sdk";

Me.CreateProductCollection({
  ID: "wishlist",
  Name: "Wishlist"
})
.then((productCollection) => {
  console.log(productCollection);
})
.catch((ex) => console.log(ex));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Me, OrderCloudError, ProductCollection } from "ordercloud-javascript-sdk";

Me.CreateProductCollection({
  ID: "wishlist",
  Name: "Wishlist"
})
.then((productCollection: ProductCollection) => {
  console.log(productCollection);
})
.catch((ex: OrderCloudError) => console.log(ex));
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var productCollection = new ProductCollection
{
  ID = "wishlist",
  Name = "Wishlist"
};

try {
  ProductCollection response = await Me.CreateProductCollection(data);
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}
```

:::
::::

#### Add products to wishlist

Add products using `PUT /me/productcollections/{productCollectionID}/{productID}`:

::::codetabs
:::codetab{title="HTTP"}

```http
PUT https://sandboxapi.ordercloud.io/v1/me/productcollections/wishlist/enterprise-product-id HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Me } from "ordercloud-javascript-sdk";

Me.CreateProductCollectionEntry("wishlist", "enterprise-product-id")
.then(() => {
  console.log("Successfully added a product to your wishlist!");
})
.catch((ex) => console.log(ex));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Me, OrderCloudError } from "ordercloud-javascript-sdk";

Me.CreateProductCollectionEntry("wishlist", "enterprise-product-id")
.then(() => {
  console.log("Successfully added a product to your wishlist!");
})
.catch((ex: OrderCloudError) => console.log(ex));
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

try {
  await Me.CreateProductCollectionEntry("wishlist", "enterprise-product-id");
  Console.WriteLine("Successfully added a product to your wishlist!");
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}
```

:::
::::


#### View wishlist products

Retrieve wishlist contents using collection listing endpoint:

::::codetabs
:::codetab{title="HTTP"}

```http
GET https://sandboxapi.ordercloud.io/v1/me/productcollections/wishlist/products HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Me } from "ordercloud-javascript-sdk";

Me.ListProductCollectionEntries("wishlist")
.then((wishlist) => {
  console.log(wishlist.Items);
})
.catch((ex) => console.log(ex));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Me, OrderCloudError } from "ordercloud-javascript-sdk";

Me.ListProductCollectionEntries("wishlist", "enterprise-product-id")
.then((wishlist: ListPageWithFacets<BuyerProduct) => {
  console.log(wishlist.Items);
})
.catch((ex: OrderCloudError) => console.log(ex));
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

try {
  ListPageWithFacets<BuyerProduct> response = await Me.ListProductCollectionEntries("wishlist", "enterprise-product-id");
  Console.WriteLine(response.Items);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}
```

:::
::::

#### Remove wishlist products

Remove products using `DELETE /me/productcollections/{productCollectionID}/{productID}`:

::::codetabs
:::codetab{title="HTTP"}

```http
DELETE https://sandboxapi.ordercloud.io/v1/me/productcollections/wishlist/enterprise-product-id HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Me } from "ordercloud-javascript-sdk";

Me.DeleteProductCollectionEntry("wishlist", "enterprise-product-id")
.then(() => {
  console.log("Successfully removed a product from your wishlist.");
})
.catch((ex) => console.log(ex));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Me, OrderCloudError } from "ordercloud-javascript-sdk";

Me.DeleteProductCollectionEntry("wishlist", "enterprise-product-id")
.then(() => {
  console.log("Successfully removed a product from your wishlist.");
})
.catch((ex: OrderCloudError) => console.log(ex));
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

try {
  await Me.DeleteProductCollectionEntry("wishlist", "enterprise-product-id");
  Console.WriteLine("Successfully removed a product from your wishlist.");
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}
```

:::
::::


### Implementation considerations

#### Feature applications

Product Collections enable various features:

- Wishlists
- Save for later functionality
- Favorites lists
- Custom collection types

#### System limitations

Important constraints:

- Buyer user access only
- Individual user visibility
- 500 product limit per collection
- Unlimited collections per user
- Visibility-dependent product access